Skip to main content

0001 — Documentation stack

Status: Accepted · Date: 2026-06-03

Context​

The monorepo had no maintainable documentation system — only AGENTS.md (agent instructions, now partly stale) and boilerplate READMEs. We want documentation that future developers (and AI agents) keep up to date, covering three kinds of knowledge: prose explanation, TypeScript API reference, and component states.

Decision​

Use the right tool for each documentation type, unified by a single site:

  • Markdown in /docs — purpose, setup, architecture, workflows, decisions. The source of truth for "how and why".
  • TypeDoc → docs-site/static/typedoc — generated reference for the exported APIs of @enode/core and @enode/ui.
  • Storybook → docs-site/static/storybook — reusable @enode/ui components and their states.
  • Docusaurus (docs-site/) — the central website. Serves the repo-root /docs folder and links to the TypeDoc + Storybook builds in its static/.

A single reusable script, scripts/build-docs.mjs (npm run docs:build), builds TypeDoc + Storybook directly into docs-site/static, then builds Docusaurus — no copy step. npm run docs:check (lint + typecheck + docs:build) is the CI gate.

Notable choices​

  • All doc tooling lives under docs-site/ (its own .storybook/, typedoc.json) and outputs into docs-site/static; nothing is generated at the repo root, keeping the monorepo tidy.
  • Docusaurus shares the root node_modules (no separate package.json), so one root npm install covers the whole docs build.
  • Storybook uses @storybook/nextjs-vite with the @tailwindcss/vite plugin wired in viteFinal, so stories render with the real @enode/ui design tokens (there is no root PostCSS config to auto-detect).
  • TypeDoc points at packages/*/src, not the apps — the shared packages are the stable public API surface.
  • No OpenAPI/Swagger. These are clients; there is no generated API client or OpenAPI artifact to document.

Consequences​

  • One command (npm run docs:build) produces the whole documentation website.
  • Heavy dev dependencies are added to the root (Storybook, Docusaurus, TypeDoc).
  • Documentation must be updated alongside code — enforced by docs:check in CI, a PR checklist, and a shared pre-push hook (see CONTRIBUTING.md and the "Documentation Rules" in CLAUDE.md).