English for Docusaurus Developers
Vocabulary for developers building documentation sites with Docusaurus — versioned docs, sidebars, MDX, and the docs-as-code workflow — for teams writing technical documentation in English.
Docusaurus, built by Meta’s open-source team, is the default choice for a lot of teams building versioned, searchable product documentation. Because documentation sites have their own concerns — versioning, sidebars, docs-as-code review — the vocabulary around Docusaurus blends React/MDX terms with documentation-specific ones. This guide covers what you’ll need when writing docs, reviewing a docs PR, or explaining the site’s structure to a new technical writer.
Docs-as-Code Fundamentals
Docs-as-code — treating documentation like source code: written in plain text files, version-controlled, and reviewed through pull requests rather than a separate CMS workflow. “Because we’re docs-as-code, a documentation fix goes through the exact same PR review process as an engineering change.”
MDX — markdown that supports embedding React components directly inside the content, letting you mix prose with interactive elements like tabs or live code samples.
“We used an MDX component to add a live, runnable code sandbox directly in the middle of the getting-started guide, instead of a static code block.”
Front matter — the YAML metadata block at the top of a doc file, setting its title, sidebar position, and other page-level configuration.
“Setting
sidebar_position: 2in the front matter is how we control ordering, without maintaining a separate sidebar config for every single page.”
Versioning
Docs Versioning
Docs versioning lets you publish and maintain multiple versions of your documentation simultaneously — so users on an older release see docs matching their version, not the latest.
“A customer on v2 was confused by docs describing a v3-only feature — that’s exactly the kind of mismatch docs versioning is meant to prevent.”
Version Snapshot
A version snapshot freezes the current state of your docs folder into a versioned copy when you cut a new release, so future edits to docs only affect the “next” (unreleased) version.
“When we cut v3, we took a version snapshot of the docs — from now on, only intentional backports touch the v2 snapshot.”
Next / Unreleased Version
The next version (sometimes labeled “unreleased”) tracks documentation for features not yet shipped, kept separate from the current stable version.
“We wrote the new API’s docs against the next version, so they don’t show up for stable users until the release actually ships.”
Site Structure
Sidebar — the configurable navigation tree shown alongside doc pages, either auto-generated from the folder structure or explicitly defined in a sidebars file.
“We switched from an auto-generated sidebar to an explicit one once the folder structure stopped matching the order we wanted readers to follow.”
Plugin — a Docusaurus extension adding functionality beyond the core docs/blog setup — search integration, a changelog page, or custom data sources.
“We added a plugin that pulls our OpenAPI spec and generates a fully interactive API reference page automatically.”
Preset — a bundle of plugins and themes configured together for a common use case (like the classic preset combining docs, blog, and a themed layout).
“The classic preset gave us docs, blog, and a working theme out of the box — we only needed to add one extra plugin for search.”
Content and Review Workflow
Admonition — a styled callout block (note, tip, warning, danger) used in markdown to highlight important information without breaking the reading flow.
“We wrapped the breaking-change warning in a
:::dangeradmonition so it’s visually impossible to miss while skimming the page.”
Broken link checker — Docusaurus validates internal links at build time and fails the build if any point to a non-existent page, catching stale references before they ship.
“The build failed because a link pointed to a page we’d since renamed — the broken link checker caught it before it reached production.”
Doc ID — a stable identifier for a doc page, independent of its file path, used for cross-referencing so links don’t break if a file gets moved or renamed.
“We reference pages by doc ID in our sidebar config, so reorganising the folder structure later won’t silently break internal links.”
Search and Discoverability
Local search vs. hosted search (Algolia DocSearch) — Docusaurus supports a lightweight local search plugin for smaller sites, or Algolia’s hosted DocSearch for larger sites needing faster, more relevant results.
“We moved from local search to Algolia DocSearch once the docs grew past a few hundred pages — search relevance improved noticeably.”
Explaining Docusaurus to a Documentation Team
| Situation | Phrase |
|---|---|
| Explaining docs-as-code to a new technical writer | ”Every change to the docs is a pull request — the same review process engineering uses, which means changes get feedback before they go live.” |
| Justifying versioned docs | ”Customers on the older release need to see docs that match what they actually have installed — that’s what versioning solves.” |
| Describing a broken link build failure | ”The build isn’t broken by accident — it caught a stale internal link before it could reach production, which is exactly what it’s supposed to do.” |
| Discussing search choice | ”Once we passed a few hundred pages, local search started returning weak results — Algolia’s hosted search noticeably improved relevance.” |
Common Mistakes
- Calling a version snapshot a “backup” — it’s an intentional, separately maintained copy of docs tied to a release, not a passive backup mechanism.
- Saying “the docs are broken” when a build failure is actually the broken link checker doing its job — distinguish an intentional safeguard from an actual bug.
- Referring to any React component embedded in markdown as “just markdown” — content using components is specifically MDX, which has different capabilities and constraints.
Practice Exercise
- Explain, in two sentences, why a company might maintain multiple versions of its documentation simultaneously.
- Write a short PR description for adding a new admonition-based warning to an existing doc page.
- Draft an onboarding note for a technical writer explaining the difference between the “next” version and the current stable version.