English for Docusaurus Developers

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: 2 in 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 :::danger admonition 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

1. Explain, in two sentences, why a company might maintain multiple versions of its documentation simultaneously.
2. Write a short PR description for adding a new admonition-based warning to an existing doc page.
3. Draft an onboarding note for a technical writer explaining the difference between the “next” version and the current stable version.

Related Resources

• English for Hugo Static Site Developers
• How to Write API Documentation in English

Navigating the Docs Landscape – Vocabulary for Docusaurs

Let’s face it: documenting software effectively isn’t just about what you’re describing; it’s fundamentally about how you communicate that information. As a Docusaurus developer, you’ll be working with MDX, sidebars, and versioned documentation – all requiring precise English to ensure clarity and maintainability. This section focuses on the specific vocabulary needed to navigate this workflow and collaborate effectively within a technical documentation team.

One of the biggest challenges for non-native speakers is moving beyond literal translations and embracing the nuances of professional English. For instance, simply stating “this function does something” isn’t as effective as “this function performs the following operation.” The latter conveys a more confident and precise understanding. Similarly, phrases like “it’s up to you” can be misinterpreted; “you are responsible for…” is far clearer and sets expectations. We’ll also look at phrasing common in code reviews – critical for Docusaurus development – focusing on constructive feedback rather than blunt criticism.

Another key area is terminology related to the ‘docs-as-code’ approach we use with Docusaurus. Terms like “branching,” “pull request,” and “merge” are frequently used, and understanding their context within a software development workflow is vital. It’s not enough to simply know what these actions do; you need to understand why they’re done – for example, “creating a branch allows us to work on new features in isolation without affecting the main codebase.”

Finally, mastering vocabulary related to Docusaurus-specific concepts like MDX components and sidebars is crucial. Knowing the difference between an “inline” component and a “block” component will significantly impact your ability to structure your documentation effectively.

Here’s a quick example of how this might translate into a Slack message:

Instead of: "This needs fixing!"
Try: "Could we explore optimizing the performance of this section? I noticed [specific observation] and suspect it's impacting page load times."

Let’s look at a practical example, focusing on a code review comment. A developer might receive feedback like this: “The API endpoint documentation is unclear.” This could be improved with phrasing such as, “I’m finding the input parameters for this endpoint somewhat ambiguous. Could you clarify the expected data types and potential error codes?” or even “It would be helpful to add a brief example of how to call this endpoint.”

// Example: Docusaurus MDX component definition (simplified)
import { Docs } from "@docusaurus/core";

const MyComponent = ({ title, content }) => (
  <Docs>
    <Docs.Section title={title}>
      {content}
    </Docs.Section>
  </Docs>
);

export default MyComponent;

This code snippet demonstrates a simplified example of how you might use MDX within Docusaurus – highlighting the importance of clearly defining components and their properties. Mastering these vocabulary elements will significantly enhance your ability to contribute effectively to technical documentation projects using Docusaurus.