Skip to main content

ADR-003: Use Docusaurus for Documentation

Status: Accepted

Context​

The repository requires a dedicated engineering documentation application with structured navigation, MDX content, category metadata, and future customization capabilities.

The original documentation workspace used Next.js.

Decision​

Replace the Next.js documentation application with Docusaurus.

Store documentation content under:

apps/docs/content/

Use MDX for documentation pages.

Use an autogenerated filesystem-based sidebar with _category_.json metadata.

Consequences​

  • documentation concerns are separated from the main product application
  • navigation can grow directly from the content structure
  • MDX allows future React component integration
  • Docusaurus provides documentation-specific routing and generated category pages