# Spot Linker

[日本語 README](README.ja.md)

Spot Linker helps you turn mentions in the note you are editing into links to other notes in your Obsidian vault. It looks for other notes' file names, titles, and aliases, then lets you confirm the destination before a link is written.

For example, text that says `cognitive load` can suggest `cognitive load.md` or a note with that alias. Nothing is changed until you choose **Create link**.

Scanning runs only when you start it. Core features run locally and do not send note content to an external service.

## Improvements in this version

This release makes everyday linking more reliable:

- Code, existing links, quotes, and similar protected text are skipped so that suggestions stay focused on ordinary prose.
- While the note-name list is rebuilt, the previous list remains available. A failed rebuild does not remove the last working list.
- Highlights from before an edit are removed automatically, reducing the chance of creating a link from out-of-date text.

## Three actions to start with

1. Open a note and run **Scan current note and highlight candidates** from the command palette or ribbon icon.
2. Hover a highlight on desktop, or tap it on mobile, to inspect the possible destination.
3. Choose **Create link** only when the destination is correct.

To remove highlights, click the ribbon icon again, click the `Spot: count` status item, or run **Clear highlights**. Showing a candidate never changes your note.

## Examples

### Link a note name from ordinary text

If your vault contains `cognitive load.md`, Spot Linker can highlight `cognitive load` in another note. Review the preview and create a link when it points to the intended note.

Japanese and Han text can match inside continuous text without surrounding spaces. When a short and long term overlap, the longer term is preferred.

### Use abbreviations and alternate names

Add alternate names to the destination note's frontmatter:

```yaml
---
aliases:
  - cognitive load theory
  - CLT
---
```

Enable **Use aliases** in Spot Linker settings. If an abbreviation matches more than one note, Spot Linker shows all candidates rather than choosing one for you.

### Use dated reference notes

For a note such as `2024-03-15-sleep-study.md`, enable **Use title key phrases** to also suggest `sleep study`. If generic terms create too many candidates, first limit **Include folders**, then add terms to **Stop words** or **Ignored terms**.

## Use it with DetailSearch Linker

[DetailSearch Linker](https://github.com/zoupuyo-obsidian/obsidian-detailsearch-linker) searches the **body text** of other notes. Spot Linker searches their **names, titles, and aliases**.

- Use Spot Linker when you know the name or alternate name of the note you want.
- Use DetailSearch Linker when you remember a phrase but not which note contains it.

Both plugins can be enabled together. They do not share settings or results, and running one does not start the other. If both highlight the same text, review the destination before creating a link.

## Recommended first settings

Start with these settings:

- **Use filename stems**, **Use frontmatter title**, and **Use aliases**: on
- **Use title key phrases**: off
- **Minimum term length**: 3
- **Batch-link without preview**: off

This starts with exact note names and aliases. Enable title key phrases only if you need more candidates.

### When there are too many candidates

1. Set **Include folders** to the folders that contain useful destination notes.
2. Add recurring unwanted terms to **Ignored terms**.
3. Add generic title words to **Stop words**, or turn off **Use title key phrases**.

### When there are no candidates

- Confirm that the destination note is inside **Include folders**.
- Check that the needed source is enabled: file name, `title`, or `aliases`.
- Existing links, code, math, and frontmatter are intentionally skipped.
- For short Latin abbreviations, review **Minimum term length** and the **2-character allow list**.

## Settings

| Setting | Purpose |
| --- | --- |
| **Include folders** | Where destination notes are found. Empty means the whole vault except excluded folders. |
| **Exclude folders** | Folders that should not provide link destinations. |
| **Filename / title / aliases / title key phrases** | Which note information becomes a candidate term. |
| **Minimum term length** | The minimum length for Latin terms and title-derived terms. Default: 3. |
| **Stop words** | Generic words excluded from title-derived terms. |
| **Ignored terms** | Terms that should never be highlighted. |
| **Suppress current note title fragments** | Reduces ambiguous candidate terms that come from the note you are editing. |
| **Batch-link without preview** | Links only spans with one destination. Off by default. |

When the entire vault is included and there are many notes, Spot Linker asks for confirmation before the first index is built. For large vaults, choose destination folders before your first scan.

## Install and update

1. Open the desired version on [GitHub Releases](https://github.com/zoupuyo-obsidian/obsidian-spot-linker/releases).
2. Download `main.js`, `manifest.json`, and `styles.css`.
3. Place the files in `.obsidian/plugins/spot-linker/` inside your vault.
4. Enable **Spot Linker** under **Settings → Community plugins**.

For an update, replace all three files from the same release, then disable and enable the plugin again or restart Obsidian. When a release includes `SHA256SUMS`, you can use it to verify the downloaded files.

If Spot Linker is listed in the Community plugins directory, you can install and update it there instead.

## Desktop and mobile

Hover highlights on desktop. Tap a highlight or its count badge on mobile. Mobile does not show the status-bar item, so use the ribbon, preview, or command palette to clear highlights.

## Privacy

Indexing and matching run inside Obsidian. Core features do not make network requests.

## Development

```bash
npm test
npm run lint
npm run build
npm run verify:release
```

After replacing a development build, disable and enable the plugin again or reload Obsidian.

## License

[0-BSD](LICENSE)