Spot Linker

日本語 README

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:

---
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 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.
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

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