docusaurus-glossary

Use when working with docusaurus-plugin-glossary to configure, manage glossary terms, troubleshoot issues, and explain features

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill provides comprehensive support for the docusaurus-plugin-glossary, assisting developers and technical writers in configuring the plugin, managing glossary terms, and troubleshooting integration issues to enhance documentation clarity and user experience.

Use Cases

  • Plugin Configuration: Quickly generate and validate the configuration code for docusaurus.config.js, including setting up glossary paths and enabling auto-linking features.
  • Glossary Management: Streamline the creation and maintenance of the glossary.json file by adding new terms, definitions, abbreviations, and related terms with correct JSON formatting.
  • Technical Troubleshooting: Diagnose and resolve common issues such as auto-linking failures, cache conflicts, or environment-specific bugs in Docusaurus v3 projects.
  • Feature Implementation: Get step-by-step guidance on using advanced features like the <GlossaryTerm /> MDX component for manual term control and customizing the GlossaryPage.
namedocusaurus-glossary
# IMPORTANTKeep description on ONE line for Claude Code compatibility
descriptionUse when working with docusaurus-plugin-glossary to configure, manage glossary terms, troubleshoot issues, and explain features

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:

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