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.

Links whole notes as terms — not the headings inside them. If you want a word to link to an individual heading in a file, that's the one thing this plugin leaves out, and its sibling Heading Linker does exactly that, on the same matching engine. The two are made to work together.

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

The plugin ships as main.js, manifest.json and styles.css. Eight 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.

_{Every change is previewed before it's written.}

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

Before — highlighted, text still plain	After — real links

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

Each row in the tooltip and the picker carries a second line saying what it is, and — when the word reached that term through one of its aliases rather than its title — which alias. That last part matters when an alias on one term collides with another term's title: you interact with "A", the list offers "A" and "B", and the line under "B" says it answers to "A" as well.

_{A word that fits two terms gets a distinct underline and a tooltip listing them.}

_{Acting on it asks which term you meant.}

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. A title held by more than one note — say Status in two of your glossary folders — carries a [1] [2] marker instead: a [[Status]] link can't say which note it means, so click a number to open that one and decide which to rename.
• 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 its base form to Excluded words as word*, so no form of it comes back on the next scan). 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. Eight language modules are bundled in, 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 Юнит. Beyond the stemmer there is a rule for the fleeting vowel, which no suffix trimming can reach (песок/песка, отец/отца, палец/пальца), and a table for the irregular plurals: the ten -мя neuters (имя/имена), the stem-growing nouns (мать/матери, небо/небеса) and the suppletive ones (человек/люди, ребёнок/дети).
• uk.js (Ukrainian) — the plugin's own light stemmer, handling the о/і and е/і vowel alternation in closed syllables (кіт/кота, ніч/ночі), plus a table for the irregular plurals (людина/люди, дитина/діти, ім'я/імена, however the apostrophe is typed).
• en.js (English) — Porter stemmer (Porter 1980, public domain): units → unit, running → run. On top of it, tables for the plurals no stemmer reduces: classical (cacti → cactus, indices → index), native (mice → mouse, children → child) and -f/-ves (wolves → wolf, lives → life). The tables apply to a compound's last word too, so grandchildren → grandchild and salespeople → salesperson. Greek -sis nouns are too many to list, so they follow a rule instead: prognoses → prognosis, neurogeneses → neurogenesis. An invariant plural like moose needs nothing.
• 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. German umlaut plurals (Maus/Mäuse, Buch/Bücher) come out of the stemmer already; French adds a table for the closed -ail/-aux group and the suppletive plurals (travail/travaux, œil/yeux).
• la.js / el.js (Latin / Greek) — the plugin's own: a Schinke case stemmer for Latin (rosae → rosa), and for Greek a light stemmer that folds polytonic diacritics so accented case forms meet (λόγου → λόγος). Both stay off by default; English already covers the latinised plurals an English note actually uses.

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 ignores case, except for terms that look like acronyms — see Smart case for acronyms below. 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. The modules are shared with the sibling linker plugins, so they live in the obsidian-linker-shared submodule and a new one benefits every plugin at once. 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 _template.js to src/shared/morphology/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 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/shared/morphology/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 first 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

Priority among linker plugins

Install more than one linker and they will sometimes claim the same word or the same link. It goes to whichever sits highest in Settings → Maintenance → Priority among linker plugins, and the loser stands aside — no double highlight, one entry in the right-click menu, one merged list of suggestions while you type.

The list appears only when another linker is installed. Each plugin moves itself, so reordering may take a move from more than one settings tab; every arrangement is reachable that way.

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 new terms land in. 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

How a highlight looks is exposed to the Style Settings plugin under a Glossary Linker section, so you can restyle it from a UI. Without Style Settings, or left at default, a highlight follows your theme's link color with a dotted underline and nothing else changes.

Every colour picker opens on the colour actually in use and follows your theme until you pick one; every option is a plain CSS variable or a class on body, so a snippet in .obsidian/snippets/ does just as well:

• Links — --glossary-link-color, --glossary-link-color-hover, --glossary-underline-style, --glossary-underline-style-hover, --glossary-underline-width, --glossary-underline-offset, --glossary-link-background, --glossary-link-background-hover, --glossary-link-radius, --glossary-link-weight; body.glossary-link-italic, body.glossary-quiet
• Ambiguous terms — --glossary-ambiguous-underline-style, --glossary-ambiguous-underline-width, --glossary-ambiguous-color, --glossary-ambiguous-symbol, --glossary-choices-width; body.glossary-mark-after
• Autocomplete and panel — --glossary-panel-font-size; body.glossary-hide-suggestion-path, body.glossary-dense, body.glossary-roomy

To mark collisions, set Ambiguous-term colour, or type anything into Ambiguous-term symbol — a character or an emoji, shown before the word unless you turn on Put the symbol after the word. The colour marks the word at rest; hovering shows the ordinary hover colour, and the double underline keeps saying it is ambiguous either way.

Show highlight only on hover leaves the ambiguity symbol visible, so a collision is still easy to spot on an otherwise quiet page.

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.

The glossary overview's usage and candidate scans are cached per note: a Rescan only re-reads notes whose file changed since the last one, and the cache drops itself whenever the term index is rebuilt (so counts never lag the glossary). The first scan of a large vault still reads every note; later ones are near-instant.

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 and el.js are 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 live in the shared submodule, under src/shared/morphology/languages/, and are bundled in through src/shared/morphology/builtin-languages.js; adding a language means contributing a module there and rebuilding (see languages/README.md). Nothing is loaded or executed at runtime.

Generic code shared with the sibling linker plugins lives in src/shared/, a git submodule of obsidian-linker-shared. Clone with --recurse-submodules so the build can find it:

git clone --recurse-submodules https://github.com/max-fluff/obsidian-glossary-linker
npm install      # once, installs esbuild
npm run build    # bundle src/ -> main.js

In an existing clone without the submodule, run git submodule update --init first.

src/ layout:

• main.js — the Plugin class: lifecycle, commands, language loading, scope, small shared helpers; applies the mixins below.
• constants.js — default settings.
• 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.
• vault-suggest.js — vault folder/file autocomplete for the settings fields (feature-detected).
• term-suggest.js — the editor autocomplete (EditorSuggest, feature-detected).
• shared/ — git submodule shared with the sibling linker plugins: markdown helpers, the i18n engine, the folder-list settings editor, and morphology/ (the language modules, their contract and validateLanguage()). Interface strings live per-plugin in locales/.

main.js is generated; edit src/ 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 everything the plugin draws: highlight color and underline, the marker-pen background, how ambiguous terms are told apart, and the overview panel's density.
• 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 — the rest of the linker family. Two of them highlight words already in your notes and link them; two autocomplete a name into a deep-link that lands on the exact spot.

Heading Linker — the file-based sibling of this plugin: each heading inside a chosen file is a term, matched in any word form and turned into a link, on the same matching engine. Works on desktop and mobile.

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.

Reference Linker — autocompletes links to external documents (PDF, Office, images) and inserts a deep-link that opens them at the right page in an external viewer. Desktop-only.

License

MIT, see LICENSE. Bundled third-party notices are in THIRD_PARTY_NOTICES.md.