docusaurus-glossary
Use when working with docusaurus-plugin-glossary to configure, manage glossary terms, troubleshoot issues, and explain features
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.
| name | docusaurus-glossary |
|---|---|
| # IMPORTANT | Keep description on ONE line for Claude Code compatibility |
| description | Use 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.jsonwith 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