Skip to main content

125. Docusaurus for Documentation

Status: Accepted Date: 2025-07-06

Context​

We need a powerful and flexible framework to build and maintain our technical documentation sites. The requirements include support for Markdown/MDX, content versioning, a searchable and navigable UI, a plugin architecture for extensibility, and the ability to be themed and customized.

Building such a framework from scratch would be a massive undertaking. We need to choose an existing static site generator that is well-suited for technical documentation.

Decision​

We will use Docusaurus as the primary framework for all our documentation sites, including the internal developer portal (toma) and the public-facing website (kaido.team).

Docusaurus is a static site generator built by Facebook, specifically designed for creating and maintaining open source project documentation. It is built on React, supports MDX out of the box (allowing us to embed React components directly in Markdown), and has a rich ecosystem of features and plugins that meet all our requirements.

Our two sites will be configured as separate Docusaurus instances within the platform/docs directory.

Consequences​

Positive:

  • Feature-Rich: Docusaurus provides a huge number of documentation-centric features out of the box, including versioning, search (via Algolia integration), internationalization, and theming. This saves us an enormous amount of development time.
  • MDX Support: The ability to use MDX is a killer feature. It allows us to create rich, interactive documentation by embedding custom React components directly into our Markdown files.
  • Extensible Plugin System: Docusaurus has a robust plugin architecture that allows us to add custom functionality, such as the fdd-auto-collection system (adr://fdd-auto-collection).
  • Strong Community and Support: As a popular open source project, Docusaurus has a large community and is actively maintained, ensuring it will remain a viable choice for the long term.

Negative:

  • React-Based: The entire framework is based on React. While this is part of our core tech stack, it does mean that customizing themes or plugins requires React knowledge.
  • Build Times: As the documentation grows, the time it takes to build the static sites can increase.
  • Opinionated Structure: Docusaurus has an opinionated file and directory structure that we must adhere to.

Mitigation:

  • Aligned Tech Stack: The dependency on React is a positive for us, as it aligns with our frontend technology choices and allows our developers to use their existing skills.
  • Incremental Builds: Docusaurus has good caching and support for incremental builds during development, which helps keep build times manageable. For production builds, the time is a reasonable trade-off for the quality of the output.
  • Convention Over Configuration: The opinionated structure is a benefit, as it provides a clear, consistent way to organize content, reducing cognitive overhead for developers.