Skip to main content

A glossary plugin for Docusaurus

· 2 min read
Max Clayton Clowes
Max Clayton Clowes
mcclowes
mcclowes/docusaurus-plugin-glossary
Loading…

Fetching repository details…

⭐ 0🍴 0

I've always been frustrated by how technical documentation often assumes readers know all the jargonjargon Technical jargon is a type of language that is used to describe technical concepts in a precise and concise manner. It is often used in scientific, engineering, and technical fields.. Whenever I build a site with DocusaurusDocusaurus A static site generator for React-based websites. Docusaurus is used to build this website., I wanted a way to automatically link and explain key terms, so readers can hover to see definitions without breaking their flow.

There used to be plugins for this, but these open source projects all went stale.

That's why I built docusaurus-plugin-glossary - a plugin that automatically detects glossary terms in your markdown content and turns them into interactive tooltips.

The solution​

The plugin does two things well:

  1. Interactive tooltips: Hover over any linked term (like this - DocusaurusDocusaurus A static site generator for React-based websites. Docusaurus is used to build this website.) and see its definition instantly. Click to navigate to the full glossary page for related terms.

  2. Automatic term detection: It scans your markdown files and automatically links glossary terms with a subtle dotted underline. No manual markup required.

The magic happens through a remark plugin that processes your markdown before it hits the browser. It respects word boundaries (so "APIAPI A set of rules and protocols that allows different software applications to communicate with each other. APIs define the methods and data formats that applications can use to request and exchange information." doesn't match "application"), and it smartly skips terms inside code blocks, links, or existing components.

Technical highlights​

  • Built as a proper DocusaurusDocusaurus A static site generator for React-based websites. Docusaurus is used to build this website. plugin following their plugin architecture
  • Uses remark to process markdown at build time
  • React components for the tooltip UI and glossary page
  • Full TypeScript support
  • Configurable term detection with sensible defaults

Try it out​

You can install it from npm:

npm install docusaurus-plugin-glossary
docusaurus-plugin-glossary
Loading…

Fetching package details…

Or check out the GitHub repository for documentation, examples, and source code.

Links: