docusaurus-glossary

mcclowes's avatarfrom mcclowes

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

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 11, 2025
[Developer Tools]

When & Why to Use This Skill

This Claude skill streamlines the integration and management of the docusaurus-plugin-glossary for Docusaurus v3 projects. It empowers developers and technical writers to efficiently configure plugin settings, maintain a centralized glossary database, and resolve technical issues related to auto-linking and MDX components, ensuring a professional and navigable documentation experience.

Use Cases

  • Plugin Configuration: Quickly set up and optimize docusaurus.config.js with the correct glossary paths, route settings, and auto-linking preferences.
  • Glossary Term Management: Efficiently add, update, or organize terms, definitions, and abbreviations within the glossary.json file to maintain a single source of truth.
  • Troubleshooting Auto-linking: Identify and fix issues when terms fail to link automatically, including verifying file paths, checking word boundaries, and clearing build caches.
  • MDX Component Implementation: Guidance on using the <GlossaryTerm /> component for manual control over term highlights and tooltips within complex documentation pages.
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