Skip to main content

ADR-009: Documentation Platform — Docusaurus

Status: Accepted Date: 2026-03-16

Context​

The PSSaaS project has 14+ markdown documents covering architecture, legacy analysis, business logic deep-dives, and strategic context. These documents need a presentation layer that supports navigation, search, and rich content (diagrams, interactive components).

Options considered:

  • MkDocs (Material theme): Python-based, used by PowerSeller X. Simple and fast.
  • Docusaurus: React-based, MDX support, versioning, search plugins.
  • Raw markdown in Git: No presentation layer, read in IDE or GitHub.
  • Confluence/Notion: SaaS documentation tools. Vendor lock-in, no code-adjacent workflow.

Decision​

Docusaurus (React-based static site generator). Run locally in Docker for authoring. Deploy to Azure Static Web App for team access. MDX support allows embedding React components.

Key factors:

  • MDX support: Can embed interactive React components (mockups, ER diagram explorers, calculation visualizers) directly in documentation
  • React alignment: Same technology as the SaaS frontend — component prototyping in docs can migrate to the app
  • Containerized: Runs in Docker, no Node.js install required on developer machines
  • Versioning: Built-in doc versioning for tracking architecture evolution
  • Search: Algolia DocSearch or local search plugins

Consequences​

Positive:

  • Component prototypes built in docs can be promoted to the actual application
  • React developers can contribute to documentation with familiar technology
  • Static site deploys cheaply to Azure Static Web App
  • MDX allows mixing prose and interactive content

Negative:

  • Node.js dependency (contained in Docker, so minimal impact)
  • Heavier than MkDocs for simple markdown rendering
  • Different doc platform from PowerSeller X (MkDocs) — no doc tooling reuse across products