Skip to main content

127. Markdown and MDX for Content

Status: Accepted Date: 2025-07-06

Context​

We need to choose a standard format for authoring the content of our documentation sites. The ideal format should be:

  • Easy for developers to write and learn.
  • Able to handle standard text formatting, code blocks, images, and links.
  • Extensible, allowing for the inclusion of rich, interactive components.
  • Well-supported by modern tooling.

Decision​

We will standardize on Markdown as the base format for all documentation content. Specifically, we will use the MDX variant.

MDX is a superset of Markdown that allows you to write JSX (React components) directly inside Markdown files. This gives us the best of both worlds:

  1. For simple, static content, developers can write standard, easy-to-use Markdown.
  2. For pages that require richer, more interactive content, developers can seamlessly embed custom-built React components without leaving the Markdown file.

This decision is tightly coupled with our choice to use Docusaurus (adr://docusaurus-documentation), which has excellent, first-class support for MDX.

Consequences​

Positive:

  • Excellent Developer Experience: Markdown is a universally known and easy-to-write format. MDX provides a powerful, yet simple, path to creating much richer content when needed.
  • Enables Interactive Documentation: We can create things like interactive charts, live code editors, or dynamic diagrams and embed them directly in our documentation pages. This makes the documentation far more engaging and effective.
  • Future-Proof: MDX is a modern, popular standard with a strong ecosystem. By standardizing on it, we ensure our content is portable and will be well-supported for years to come.
  • Component Reusability: We can create a library of standard documentation components (e.g., for callouts, tabs, etc.) and reuse them across the entire documentation site, ensuring consistency.

Negative:

  • Requires React Knowledge for Advanced Content: To create or use the interactive components, a developer needs to know React.
  • Tighter Coupling to React: Makes our content less portable to a non-React-based documentation framework in the future.

Mitigation:

  • Aligned Tech Stack: The requirement of React knowledge is not a significant negative for us, as React is a core part of our tech stack. Developers are already familiar with it.
  • Graceful Degradation: The core content is still standard Markdown. If we were to move to a framework that didn't support MDX, the React components would fail to render, but the base Markdown text would remain, so the content would not be entirely lost. The trade-off for the massive increase in documentation quality is well worth this risk.
  • Progressive Complexity: Developers don't need to know MDX to contribute. They can write plain Markdown, and other developers can enhance it with components later if needed.