How auto-linking works

The plugin uses a hybrid build-time + runtime approach.

Build time — the remark plugin

At build time, the remarkremarkA markdown processor. Remark plugins transform the markdown AST before it becomes HTML/JSX. plugin (src/remark/glossary-terms.ts in the source) walks your markdown AST and:

1. Scans text nodes for glossary terms (case-insensitive, whole-word)
2. Replaces matches with <GlossaryTerm term="…">match</GlossaryTerm> JSX
3. Injects import GlossaryTerm from '@theme/GlossaryTerm' at the top of the file

So this input:

Our API uses REST principles.

…becomes this MDXMDXA Markdown-based format that lets you write JSX inside your markdown, used by Docusaurus v3 for docs and pages. during compilation:

import GlossaryTerm from '@theme/GlossaryTerm';

Our <GlossaryTerm term="API">API</GlossaryTerm> uses <GlossaryTerm term="REST">REST</GlossaryTerm> principles.

What gets matched

• Whole words only. The unreleased Unicode fix also treats accented letters, non-Latin letters, numbers, and combining marks as word characters.
• Case-insensitive lookups
• Plural forms are handled — API matches APIs

What gets skipped

• Text inside fenced code blocks or inline code
• Text inside existing [links](…). The unreleased nested-link fix also skips formatted text inside links and reference links.
• Text inside existing MDXMDXA Markdown-based format that lets you write JSX inside your markdown, used by Docusaurus v3 for docs and pages. components
• Partial-word matches

Overlapping terms

When two glossary terms could both match the same span of text, the remarkremarkA markdown processor. Remark plugins transform the markdown AST before it becomes HTML/JSX. plugin resolves the conflict deterministically:

1. Subset overlap — the superset wins. If one term's matched range contains another's, the longer (containing) term is kept and the shorter is dropped.

   Given the terms outgoing wire transfer and wire transfer, the sentence:

   An outgoing wire transfer was sent.

   links the whole phrase outgoing wire transfer. The inner wire transfer match is suppressed.

2. Cross-overlap — the earlier match wins. If two matches overlap but neither contains the other, the one that starts earliest in the text is kept and the later one is dropped.

   Given the terms outgoing wire transfer and wire transfer operation, the sentence:

   An outgoing wire transfer operation was sent.

   links outgoing wire transfer because it starts first. The trailing word operation is left as plain text. Elsewhere in the document, a sentence that starts with wire transfer operation (with no preceding outgoing) would link wire transfer operation instead.

These rules apply equally to canonical terms and aliases — both are treated as matchable phrases for the purposes of overlap resolution, but the tooltip and link always point back to the canonical term.

Auto-expanding acronyms on first use

When the plugin option expandAcronymsOnFirstUse is true, the remarkremarkA markdown processor. Remark plugins transform the markdown AST before it becomes HTML/JSX. plugin rewrites the first canonical occurrence of any term that has an abbreviation so the long form is introduced inline. This enforces the technical-writing convention of writing Payment Service Provider (PSP) once at the top of a page before using PSP on its own.

docusaurus.config.js

{
  presets: [
    ['docusaurus-plugin-glossary/preset', {
      glossary: {
        expandAcronymsOnFirstUse: true,
      },
    }],
  ],
}

Given a term:

{ "term": "PSP", "abbreviation": "Payment Service Provider", "definition": "…" }

Source:

The PSP charges a fee. Each PSP has its own pricing.

Renders as:

The <GlossaryTerm term="PSP">Payment Service Provider (PSP)</GlossaryTerm> charges a fee. Each <GlossaryTerm term="PSP">PSP</GlossaryTerm> has its own pricing.

Rules

• Per file. The first occurrence in each markdown/MDXMDXA Markdown-based format that lets you write JSX inside your markdown, used by Docusaurus v3 for docs and pages. file is expanded; subsequent ones render unchanged.
• Canonical only. Only the canonical term triggers expansion — aliases and plural forms (PSPs) render unchanged.
• Abbreviation required. Terms without an abbreviation are never expanded.
• Author wins. If the long form already appears immediately before the term (e.g. you wrote Payment Service Provider (PSP) yourself), expansion is skipped to avoid duplication.
• autoLink: false is respected. Opting a term out of auto-linking also opts it out of expansion.
• Case-insensitive. A lowercase canonical mention (e.g. psp) still triggers expansion, rendering Payment Service Provider (psp).

Linking only the first occurrence

The unreleased linkOnlyFirstOccurrence option defaults to false. Set it to true in the preset's glossary options, getRemarkPlugin options, or the remarkremarkA markdown processor. Remark plugins transform the markdown AST before it becomes HTML/JSX. plugin options to link each term once per file.

Canonical names, aliases, and plurals share one occurrence. If API has the alias interface, then API, APIs, and interface together get one link. Headings, existing links, code, and MDXMDXA Markdown-based format that lets you write JSX inside your markdown, used by Docusaurus v3 for docs and pages. components don't consume the first occurrence.

This works with expandAcronymsOnFirstUse: the first canonical occurrence gets both the expansion and the link. If an alias or plural appears first, it gets the link without expansion, and later canonical occurrences stay plain text.

Runtime - the theme component

The generated MDXMDXA Markdown-based format that lets you write JSX inside your markdown, used by Docusaurus v3 for docs and pages. renders the GlossaryTerm React component. The component handles links, tooltips, focus behavior, and viewport-aware tooltip placement. No client moduleclient moduleA JS/TS file registered via a plugin's getClientModules() that runs on every client-side navigation in the browser. or separate initialization step is involved.

Theme integration

GlossaryTerm is exposed through the theme system at @theme/GlossaryTerm, which means:

• MDXMDXA Markdown-based format that lets you write JSX inside your markdown, used by Docusaurus v3 for docs and pages. files can import it without knowing the package path
• You can swizzleswizzleDocusaurus's mechanism for customizing theme components by ejecting or wrapping them in your project. it to customize the component (see Customization)
• The remarkremarkA markdown processor. Remark plugins transform the markdown AST before it becomes HTML/JSX. plugin can reference it by a stable alias

Opting out

If you don't want auto-linking, don't use the preset — register just the plugin manually without the remarkremarkA markdown processor. Remark plugins transform the markdown AST before it becomes HTML/JSX. plugin. The /glossary page and the <GlossaryTerm> component will still work, but you'll need to use the component explicitly when you want tooltips.