Skip to main content

ADR-0001: Adopt Docusaurus for Portfolio Documentation

Purpose​

Record the decision to use Docusaurus as the documentation platform for the portfolio program, including tradeoffs, consequences, and validation criteria.

Scope​

Use when​

  • establishing the baseline documentation platform for the portfolio program
  • selecting a documentation tool that supports enterprise navigation, governance, and CI gates

Do not use when​

  • selecting minor plugins or small presentation tweaks (unless they materially change the platform posture)

Prereqs / Inputs​

  • Decision owner(s): Portfolio maintainer
  • Date: 2026-01-06
  • Status: Accepted
  • Related work items: N/A (initial platform decision)
  • Related risks:
    • supply chain and dependency risk inherent to Node-based toolchains
    • risk of publishing sensitive information
    • risk of navigation/IA drift as docs scale

Decision Record​

Title​

ADR-0001: Adopt Docusaurus for Portfolio Documentation

Context​

The portfolio program requires a documentation system that is:

  • Markdown-first and author-friendly in VS Code (WSL2)
  • version-controlled and PR-governed (docs-as-code)
  • scalable to an enterprise-style information architecture
  • able to enforce quality gates (build fails on broken links)
  • deployable publicly with a professional UI/UX suitable for portfolio reviewers
  • capable of hosting technical diagrams and structured, navigable documentation

Decision​

Adopt Docusaurus (TypeScript) as the documentation platform, using:

  • filesystem-driven docs under docs/
  • autogenerated sidebar strategy governed by _category_.json
  • pnpm as the package manager
  • CI quality gate requiring pnpm build to pass before merge

Alternatives considered​

  1. MkDocs + Material

    • Pros:
      • fast, stable, simple static site pipeline
      • excellent theme and search ecosystem
    • Cons:
      • less aligned with modern JS/TS portfolio narrative (if you want interactive documentation patterns)
      • customization and “app-like” UX patterns may require more work
    • Why not chosen:
      • Docusaurus better fits a portfolio program where documentation is part of a modern web engineering story.

  2. Obsidian + Quartz

    • Pros:
      • exceptional local authoring experience (linking/graph)
      • good for rapid ideation and personal knowledge management
    • Cons:
      • governance and structured enterprise navigation requires additional conventions/tooling
      • can drift toward personal note-taking rather than polished product documentation
    • Why not chosen:
      • this repository prioritizes enterprise-grade public documentation over a personal PKM-first workflow.

  3. Custom Next.js docs

    • Pros:
      • maximum control; consistent with full-stack portfolio stack
    • Cons:
      • higher maintenance and greater risk of “building the platform instead of the content”
      • requires re-implementing many doc-native features (sidebars, versioning patterns, doc search)
    • Why not chosen:
      • Docusaurus provides a strong baseline with less platform engineering overhead.

Consequences​

  • Positive consequences:

    • Strong, industry-recognizable docs-as-code platform
    • Scales to large doc sets with predictable navigation and category governance
    • Professional “product docs” presentation suitable for external reviewers
    • Tight integration with CI gates (pnpm build)

  • Negative consequences / tradeoffs:

    • Node dependency surface introduces supply chain considerations
    • Requires discipline to avoid overusing MDX and turning docs into “app code”
    • Requires consistent IA governance to prevent nav drift

  • Operational impact:

    • Docs site becomes a deployable artifact; requires deploy/rollback runbooks
    • Build failures (links, structure) block merges and must be triaged quickly

  • Security impact:

    • Must enforce strict “no secrets” publication rules
    • Must manage dependency updates and CI integrity as first-class concerns

  • Cost/complexity impact:

    • Moderate complexity relative to MkDocs, but justified by capability and portfolio alignment

Implementation notes (high-level)​

  • Scaffold Docusaurus with TypeScript and pnpm.
  • Implement:
    • docs/index.md as the landing entrypoint
    • top-level domain folders (00-…70-…) each with _category_.json + index.md
    • internal-only scaffolding under docs/_meta/ (underscore-prefixed, not public)
  • Add CI:
    • must run pnpm build and fail on broken links.

Validation / Expected outcomes​

  • Local validation:
    • pnpm start renders site with coherent sidebar
    • pnpm build succeeds deterministically
  • Governance validation:
    • PR-only merges; build gate enforced
    • adding a new folder + _category_.json reliably produces coherent navigation
  • Reviewer validation:
    • “Start here” path is obvious and leads to domain and project dossiers

Failure modes / Troubleshooting​

  • Build instability due to dependency drift:
    • mitigation: pinned toolchain expectations; lockfile discipline; review dependency changes
  • Navigation entropy:
    • mitigation: enforce _category_.json + index hubs; consistent positions and naming
  • Accidental sensitive publication:
    • mitigation: strict policy + scanning + incident response procedure

References​

  • Project dossier (Portfolio Docs App): docs/60-projects/portfolio-docs-app/
  • Docs landing: docs/index.md
  • DevOps platform docs: docs/30-devops-platform/
  • Security posture docs: docs/40-security/
  • Operations docs: docs/50-operations/