Glossary Linker

Glossary Linker

Highlights glossary terms in your notes in any word form (declensions, plurals), lets you turn them into real links, and picks up new aliases from links you've already made by hand. It was inspired by Virtual Linker, but it matches inflected forms instead of exact spellings only.

Available in the Obsidian community catalog: community.obsidian.md/plugins/glossary-linker.

The plugin ships as main.js, manifest.json and styles.css. Six language modules are baked into main.js, so it works the moment you install it. You can add more languages as modules (see Adding a language). main.js is built from src/ with esbuild (see Development).

Contents

• What it does
  • Highlight terms in any word form
  • Turn terms into real links
  • Collect aliases from links you made
  • Suggest links as you type
  • Ambiguous terms
  • Glossary overview
• Morphology and languages
  • Which scripts fit
  • Adding a language
• Commands
  • Templates for new terms
• Settings
• Skipped contexts
• Performance
• Public API
• Licenses & credits
• Development
• Installation
• Compatibility
• Related plugins

What it does

Highlight terms in any word form

The term list comes from each glossary file's name and its aliases. Matching words are found even when inflected (unit → units, RU юнит → юнита/юниту/юнитов). The engine is multilingual and picks itself by the word's script: Russian for Cyrillic, English for Latin (more in Morphology and languages). Highlighting runs in Reading view and in the editor (Live or On save). Multi-word terms (Vision radius, hyphenated Flow-field) match as a whole, longest match first.

The highlights behave like real internal links, in both Reading view and the editor:

• hover shows the term's page preview (following your Page Preview settings, with or without a modifier key);
• click opens the glossary note — in the editor a plain click just places the cursor, Ctrl/Cmd+click follows the term, and middle-click opens it in a new tab;
• right-click opens an actions menu — link to term, exclude the word or term, open the note, and more (see Commands). Each group can be hidden under Settings → Context menu; with all off, right-click shows the native menu. On mobile, a long-press opens this menu (there's no hover preview).

Turn terms into real links

There are commands for the current note, the selection, or every note. A matching word becomes [[Title|word]]: the visible text stays exactly as you wrote it, and the link points to the glossary title. An "only first match per note" option is available, and every change is previewed before it's written.

Same words before and after — the visible text is unchanged, only the link is added:

Across the whole vault, replacements are grouped by file, with a single picker at the top for any word that matches more than one term.

Collect aliases from links you made

This scans for [[Term|some wording]] links you wrote by hand. If Term is a glossary note and the wording is custom, that wording becomes a new alias for the term; inline code and emphasis (`code`, italics) are stripped from it first. By default the wording is reduced to a base form ([[fruit|fruits]] → fruit). Aliases are de-duplicated case-insensitively, and nothing is added if the term already matches that wording anyway. Run it as a command or automatically on save. The preview gives each alias a checkbox, flags aliases that would collide with another term with ⚠ and leaves those unchecked, and lists separately the candidates skipped for already existing. A silent (on-save) collect skips colliding aliases entirely.

Alias form (aliasHarvestMode) controls how the collected wording is stored:

• lemma (default) — reduce the wording to a base (dictionary) form: EN boxes → box, RU роем → рой, юнитов → юнит. RU soft-stem nouns (боем → бой) have a dedicated rule; irregular alternations may still need a manual fix in the preview.
• literal — store the wording as written.
• both — store both.

Suggest links as you type (optional)

Turn on Autocomplete → Suggest links while typing and typing in an in-scope note offers to insert a [[link]] to a matching glossary term. The match can be a prefix of a term's title or alias (type Vis → Vision radius) or an inflected form of one. A prefix match inserts [[Term]]; an inflected form keeps your wording as [[Term|word]]. It's off by default and never fires inside the glossary folder, code, links or other protected spans. It also stays quiet when the word follows a sigil like @, # or $, so it doesn't fight tags, math or another plugin's autocomplete — see Skip after characters.

Ambiguous terms

When a word matches more than one glossary term (the same alias lives on two notes), it gets a distinct wavy underline, and hovering shows a tooltip listing every matching term instead of a single, misleading page preview. Acting on it — clicking to open, or Link to term / Open from the right-click menu — opens a small picker so you choose which term rather than silently following the first. A word that matches a single term acts immediately, as usual.

Glossary overview

A right-sidebar panel (the Open glossary overview command, or the ribbon icon) for the whole glossary at once, in two lists:

• Terms — every indexed term with how often it's used across in-scope notes; sort by usage or by name. The count is plain-text mentions, plus existing [[Term]] links when count links is ticked (on by default — so a term you've already linked everywhere isn't mistaken for unused). Terms with no uses are flagged as orphans. Click a term to open it (middle-click for a new tab), or use link all to link its occurrences across the vault.
• Candidates — frequent words that are not terms yet, so you can spot what's worth defining. Each shows how many notes it appears in and its total uses; sort by either, and set the Min notes threshold in the panel. Per candidate: create a term from it, or dismiss it with ✕ (which adds it to Excluded words, so it stays out of future scans). Collapse the section to skip the (heavier) candidate scan.

Both lists come from scanning your notes, so they refresh on demand — hit Rescan after a round of edits. By default the scan follows the linker's Link scope; tick whole vault in the panel header to scan every note regardless of scope.

Morphology and languages

Morphology is modular. Six language modules are bundled in by default, and you can add more and rebuild (see Adding a language). Each one is validated against the module contract on load and gets a toggle in settings (Matching → Languages). For a given word, the keys from every enabled language that claims it are combined, so same-script languages like English, Spanish, German and French all contribute on a Latin word. If no language claims a word, it's matched exactly (lowercased), with no morphology.

The built-in modules are stemmer code compiled into the plugin:

• ru.js (Russian) — Porter stemmer (Snowball, public domain). The keys are the union of the Porter stem and an ending strip, dropping an over-short stem. That covers both awkward cases: юнит/юнитов (the stemmer over-truncates to юн, the ending strip rescues юнит) and рой/роем, while юный/юнга/юности don't stick to Юнит.
• uk.js (Ukrainian) — the plugin's own light stemmer, handling the о/і and е/і vowel alternation in closed syllables (кіт/кота, ніч/ночі).
• en.js (English) — Porter stemmer (Porter 1980, public domain): units → unit, running → run.
• es.js / de.js / fr.js (Spanish / German / French) — ports of the UniNE / Apache Lucene light stemmers (Apache License 2.0, J. Savoy): unidades → unidad, Einheiten → einheit, chevaux → cheval. Lighter than full Snowball, but enough to link a term across its word forms.

Enable only the languages your vault actually uses. Since same-script languages combine, leaving German on in an English-only vault can occasionally over-stem a word. On first run the plugin enables English plus your Obsidian interface language (if a module exists for it); switch on any others you need.

The mode (matchMode) is a global switch for all languages: stemmer, endingStrip (a light ending trim), or exact. Each mode's actual algorithm comes from the language module. A separate setting, Alias form (aliasHarvestMode), controls how collected aliases are stored — see Collect aliases from links you made.

Which scripts fit

The matcher splits text into words (Unicode \p{L}/\p{Nd}) and reduces each one by trimming endings, so it fits alphabetic scripts with word separators and suffix inflection: Latin, Cyrillic and Greek fit fully, and Indic abugidas and Korean fit where a module strips suffixes or particles. It does not fit spaceless CJK or root-and-pattern scripts like Arabic and Hebrew, which need word segmentation or substring search that the core doesn't do.

Matching is case-insensitive. The visible text keeps the casing from your note, and collected aliases are stored lowercased.

Adding a language

A language is a small JavaScript module bundled into main.js at build time; nothing is loaded or executed at runtime. Adding one means contributing a module and rebuilding, through a pull request (see Contributing). The full contract, an annotated template and a step-by-step guide live in languages/README.md. The short version:

1. Copy languages/_template.js to languages/<id>.js (e.g. uk.js). A module exports id, name, match(word) and keys(word, mode), plus optional priority and lemma(word). Reusing a built-in id (ru/uk/en/es/de/fr) overrides it.
2. Implement match (claims a word, usually by script) and keys (returns the comparison keys for a word in the current mode — stemmer / endingStrip / exact). Two words link when their key sets overlap.
3. Register the module in src/builtin-languages.js and run npm run build.
4. Restart the plugin. The language shows up under Matching → Languages; turn its toggle on.

Every module is validated against the contract on load (src/language-api.js). A module that doesn't export an object with a valid id / name / match / keys is dropped and listed under Languages with a ⚠ marker and the reason, so the index keeps working and a mistake is easy to spot.

Commands (command palette, Ctrl+P)

• Link glossary terms: this note / selection / all notes
• Unlink glossary terms: this note / selection / all notes — the reverse of Link glossary terms: each [[Title|word]] pointing at a glossary note becomes plain word again, previewed first. Links inside code or frontmatter, links you wrote to a specific heading ([[Term#section]]), and links to non-glossary notes are left untouched.
• Collect aliases from links: this note / all notes
• Create glossary term from selection — creates a note in the glossary folder named after the selected text, and links the selection to it
• Open glossary overview — the right-sidebar panel (see Glossary overview)
• Rebuild glossary index

You can also act on a highlighted term from its right-click menu: Link to term, Link all "…" to term: this note, Link all "…" to term: all notes (the last previews changes across the whole vault), plus Add "…" to excluded words / Add "…" to excluded terms to quickly suppress a false match. Each exclude item is reversible: right-click a word or link that's already excluded and the same item reads Remove "…" from excluded words / terms. Right-click an existing glossary link for Glossary: unlink this term (turn just that link back into plain text) and Glossary: collect this alias (add this one link's wording as an alias for its term). Right-click a plain-text selection for Glossary: create term & link (create the term note and replace the selection with a link), Glossary: create term (just create and open it), and Glossary: add "…" to excluded words (suppress that word, term or not). Right-click anywhere else in the editor — empty space or a link — for Glossary: collect aliases from links (this note). Each of these groups can be toggled off under Settings → Context menu.

A status-bar counter (e.g. 3 terms) shows how many glossary terms are on the current note: plain-text mentions plus, optionally, terms already linked directly. Click it to link this note's terms (toggles under Highlighting → Status bar count).

Templates for new terms

A new term is a blank note by default. Set Term template to a note path to use that note as the body instead. These tokens are filled in when the term is created:

• {{title}} — the term name
• {{selection}} — the text you selected
• {{source}} / {{sourcePath}} — the note the term was created from
• {{date}}, {{time}} — current date/time; pass a moment format as {{date:YYYY-MM-DD}}

{{title}} is the selection with characters that aren't allowed in file names stripped out, so it matches {{selection}} for an ordinary word and differs only when the selection contains such characters.

These are the same tokens the core Templates plugin uses, so a Templates file works here too. Frontmatter in the template (an empty aliases: list, say) carries over as-is. The folder and file name come from the plugin, not the template, since the file name is the term.

To use Templater instead, leave Term template empty and add a Templater folder template for the glossary folder. The plugin creates a blank note and Templater fills it. Use one or the other for a folder, not both.

Settings

Settings are grouped into sections, each with a short description in the UI. The tables below carry the full details and tips.

Scope

You can also manage these lists from the file explorer: right-click a file or folder for Glossary: add to always-excluded (and the reverse once it's listed), or — in Listed paths only mode — Glossary: include in scope.

Matching

Highlighting

The highlight's color, underline style and offset — plus a separate underline for ambiguous terms — are exposed to the Style Settings plugin under a Glossary Linker section, so you can restyle them from a UI. Without Style Settings, or left at default, the highlight follows your theme's link color with a dotted underline.

Autocomplete

Collecting aliases

Context menu

Overview

The candidate threshold (Min notes) and the term sort live in the panel's own header, not here.

Skipped contexts

Code blocks (``` and ~~~), inline code, frontmatter, existing [[...]] and [..](..) links, and URLs are left untouched. A term is never linked inside its own note. In Reading view, links and (optionally) headings are skipped by DOM ancestry; in the editor, by the CM6 syntax tree. When a link is written into a Markdown table cell, the alias pipe is escaped ([[Term\|word]]) so the table isn't broken.

Performance

The index is built on load and rebuilt when glossary notes change (debounced). Word-form keys are cached in the index, and per-word stemmer results are memoised across a render pass (invalidated on rebuild). Scanning is token-based with longest-match-first. The editor's right-click menu reads the term straight from the clicked decoration instead of re-scanning the document.

Public API

The plugin exposes a small read-only API at app.plugins.plugins['glossary-linker'].api, so other plugins and DataviewJS can query the glossary:

A "glossary dashboard" in DataviewJS, for example:

const api = app.plugins.plugins['glossary-linker'].api;
const report = await api.getUsageReport();
dv.table(['Term', 'Uses'], report.sort((a, b) => b.count - a.count).map((r) => [r.canonical, r.count]));
// orphans:
dv.list(report.filter((r) => r.count === 0).map((r) => r.canonical));

Licenses & credits

Most bundled language modules port well-known, permissively-licensed stemming algorithms (uk.js is the plugin's own, under its MIT license). All are free for commercial and non-commercial use; the only obligation is keeping the attribution notices, which are already in each file's header.

The es/de/fr stemmers were translated to JavaScript and adapted to this plugin's module interface; per the Apache License the source files note that they are modified ports. Apache 2.0 full text: https://www.apache.org/licenses/LICENSE-2.0.

Glossary Linker itself is released under the MIT license — see LICENSE.

Development

The core is written as small CommonJS modules in src/ and bundled into main.js by esbuild. The language modules in languages/ are bundled in through src/builtin-languages.js; adding a language means contributing a module there and rebuilding (see languages/README.md). Nothing is loaded or executed at runtime.

npm install      # once, installs esbuild
npm run build    # bundle src/ -> main.js

src/ layout:

• main.js — the Plugin class: lifecycle, commands, language loading, scope, small shared helpers; applies the mixins below.
• constants.js — default settings.
• builtin-languages.js — requires the modules in languages/ so they are bundled into main.js.
• language-api.js — the language-module contract and validateLanguage().
• matcher.js — the term index and matching engine (keysFor, tokenizeForm, rebuildIndex, findMatches, termsMatchingText, protected ranges).
• highlight.js — Reading-view DOM highlighting and the CM6 editor extension.
• actions.js — turning terms into links and collecting aliases.
• api.js — the public API mixin (app.plugins.plugins['glossary-linker'].api).
• modals.js — the preview dialogs and the confirm dialog.
• settings-tab.js — the settings UI.
• folder-suggest.js — folder autocomplete for the glossary-folder field (feature-detected).
• term-suggest.js — the editor autocomplete (EditorSuggest, feature-detected).

main.js is generated; edit src/ (or languages/) and rebuild rather than editing main.js directly. node_modules/ and package-lock.json are git-ignored.

Installation

From Obsidian (recommended). Open Settings → Community plugins → Browse, search for Glossary Linker, then Install and Enable. You can also open its catalog page directly: community.obsidian.md/plugins/glossary-linker. The default languages are baked into main.js, so nothing else is needed.

Manually. Download main.js, manifest.json and styles.css from the latest release into <vault>/.obsidian/plugins/glossary-linker/, then enable the plugin in Settings → Community plugins.

Beta builds via BRAT. Add the repository max-fluff/obsidian-glossary-linker to test unreleased changes before they reach the catalog.

Compatibility

Requires Obsidian 1.4.0 or newer, and works on both desktop and mobile.

Nothing below is required — the plugin runs on its own — but it cooperates with a few others if you have them:

• Style Settings — a UI for the highlight color, underline style and offset, and the ambiguous-term underline.
• Page Preview (core plugin) — provides the hover preview on glossary links; the plugin registers as its own Glossary Linker source you can toggle independently.
• Dataview — query the glossary from DataviewJS through the public API (usage reports, orphan terms, and so on).
• Templates (core) / Templater — fill the body of newly created term notes (see Templates for new terms).

Related plugins

Also by the author — Code Linker: autocompletes references to your source code and inserts a deep-link that opens the file at the exact line in your editor (VS Code, JetBrains, …). Desktop-only.