gatsby-theme-glossary is a minimalist Gatsby Theme that builds a per-letter glossary page from MDX files, styled with Theme UI and released under the MIT license.
What is gatsby-theme-glossary?
It is a Gatsby Theme plugin that renders a glossary page from a directory of MDX files, one file per alphabet letter (a.mdx, b.mdx, and so on through z.mdx). The theme takes a configured content directory as input and produces a mobile-friendly glossary page at a configurable base path. It is built on MDX for content, uses Theme UI for styling, and is distributed as an npm package installable with yarn or npm.
Key Features
- MDX per letter — Each section is an MDX file named by its letter (a.mdx to z.mdx), mixing Markdown and JSX in the source.
- Theme UI theming — Colors, typography, and spacing inherit from your site's theme via Theme UI, with customization through the Theme UI Gatsby plugin.
- Mobile friendly — The default glossary page is responsive and works on small screens.
- Configurable paths — Two options control behavior: contentPath (default 'glossary') sets the source folder, and basePath (default 'glossary') sets the URL where the page renders.
- Shadowable description — Create src/gatsby-theme-glossary/description.mdx to add custom introduction text under the glossary title.
- Shadowable layout — The theme ships without a layout; shadow src/gatsby-theme-glossary/components/layout.js to plug in your site's layout.
- MIT license — Free to use, modify, and embed in commercial projects.
Who is it for?
- Gatsby site owners — Add a glossary to an existing Gatsby site by installing one plugin and placing MDX files into the configured folder.
- Technical documentation writers — Keep a consistent, alphabetically ordered reference of domain terms that renders as a clean page.
- Product and engineering teams — Define jargon and acronyms in one shared location for onboarding docs and internal wikis.
What can you do with gatsby-theme-glossary?
- Documentation sites: Integrate a terminology appendix alongside other Gatsby-built docs, reusing existing Theme UI styling and layout.
- Internal knowledge bases: Publish a static glossary of internal acronyms and project-specific terms for new hires.
- Open-source projects: Ship an explicit glossary with project documentation, letting contributors edit MDX files via pull requests.
How does it work?
Install with yarn add gatsby-theme-glossary, register the theme in gatsby-config.js, and create MDX files named by letter in the default 'glossary' directory (or your contentPath). Each file's name is the single letter that determines the alphabetical section. The glossary page is then generated at basePath during Gatsby's build.
Pricing
The theme is open-source under the MIT license, so it is free to use with no paid tier or account required.
FAQ
How do I install gatsby-theme-glossary?
Run yarn add gatsby-theme-glossary (or the npm equivalent) and add 'gatsby-theme-glossary' to the plugins array in your gatsby-config.js. The defaults work immediately; you only need to supply MDX files.
How do I change the glossary description?
Create a file at src/gatsby-theme-glossary/description.mdx and write your own markdown. The theme shadows this file and renders its content underneath the glossary title.
Can I use a custom layout?
Yes. The theme intentionally includes no layout. Shadow src/gatsby-theme-glossary/components/layout.js and export your own layout, for example re-exporting from your site's existing layout component.
What options does the theme accept?
It accepts two options: contentPath (default 'glossary'), the directory containing the MDX files, and basePath (default 'glossary'), the URL path for the glossary page. Set them in the plugin options object inside gatsby-config.js.
Is gatsby-theme-glossary free?
Yes. It is released under the MIT license, so you can use, modify, and redistribute it freely, including in commercial projects.
