Skip to main content

How auto-linking works

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

Build time — the remark plugin​

At build time, the remarkremark A markdown processor. Remark plugins transform the markdown AST before it becomes HTML/JSX. plugin (src/remark/glossary-terms.js 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 MDXMDX A 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 (respects word boundaries)
  • 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](…)
  • Text inside existing MDXMDX A Markdown-based format that lets you write JSX inside your markdown, used by Docusaurus v3 for docs and pages. components
  • Partial-word matches

Runtime — client modules​

The plugin registers a client moduleclient module A JS/TS file registered via a plugin's getClientModules() that runs on every client-side navigation in the browser. via getClientModules() so the tooltip/initialization logic runs on every route without you having to import anything.

Theme integration​

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

  • MDXMDX A 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 swizzleswizzle Docusaurus's mechanism for customizing theme components by ejecting or wrapping them in your project. it to customize the component (see Customization)
  • The remarkremark A 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 remarkremark A 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.