Docusaurus Glossary

Docusaurus Glossary

Quick Start

Configure the plugin in docusaurus.config.js and create a glossary JSON file:

// docusaurus.config.js
module.exports = {
  plugins: [
    [
      'docusaurus-plugin-glossary',
      {
        glossaryPath: 'glossary/glossary.json',
        routePath: '/glossary',
        autoLinkTerms: true, // Auto-detects terms in markdown
      },
    ],
  ],
}

Core Principles

• Auto-linking: Terms in markdown are automatically detected and linked with tooltips
• Glossary JSON: Single source of truth at glossary/glossary.json with terms array
• Component-based: Use <GlossaryTerm term="API" /> for manual control in MDX
• Auto-configured: Remark plugin auto-wires on Docusaurus v3 when autoLinkTerms is true

Common Patterns

Adding Glossary Terms

Create/update glossary/glossary.json with term objects containing term, definition, and optional abbreviation, relatedTerms

Troubleshooting Auto-linking

If terms aren't linking: verify glossaryPath exists, check autoLinkTerms is true, clear cache with npm run clear, restart dev server

Reference Files

For detailed documentation, see:

• configuration.md - Plugin options and setup
• usage.md - Using terms and components
• troubleshooting.md - Common issues and fixes

Notes

• Requires Docusaurus v3 and React 18
• Terms inside code blocks, links, or MDX components are not auto-linked
• Matching is case-insensitive but respects word boundaries
• Plugin includes GlossaryPage component and GlossaryTerm theme component