ADR 0088 — Docs site tooling: custom Python builder for v1
Status: Accepted Date: 2026-05-15 UTC Decider: software-architect (ratifying operator decision from 2026-04-28) Parent card: #104 Design doc: docs-site-scaffold-2026-05-15.md
Context
The public docs site at docs.raxx.app needs a static site builder. The
choices evaluated at v1 scope (T-8 days to launch):
- Custom Python builder — same pattern as
scripts/build-internal-docs.py(already in the repo, zero new dependencies). - Docusaurus — React-based, mature, strong theming. Aligns with Antlers stack. Introduces a Node/npm build step and a new dependency surface.
- VitePress — Vue-based, fast, good API doc ergonomics. Stack mismatch (Vue vs React). New dependency surface.
- mkdocs-material — Python, excellent nav and search out of the box. Requires pip dependencies not currently in the project. New dependency.
- Mintlify — Managed, fastest to ship. Introduces a third-party managed service dependency and per-seat/volume pricing. Vendor lock-in.
Decision
Use the existing custom Python builder (scripts/build-customer-docs.py)
for v1. The builder already exists in the repo (filed via #520) and the
deploy workflow (deploy-customer-docs.yml) already references it. No new
toolchain is introduced.
Post-v1 migration to Docusaurus (or equivalent) is explicitly left open and should be evaluated when the "fur-docs" custom theme card is scheduled (see Open Questions in design doc). Docusaurus remains the recommended path if a migration is warranted — it aligns with the Antlers React stack.
Consequences
- No new toolchain at v1. Python stdlib + the same markdown-to-HTML approach as internal docs. Fast to ship, zero dependency risk.
- Navigation and search are limited. The custom builder produces a flat HTML structure with a generated index. No sidebar, no full-text search. Acceptable for a 5-page v1 site; not acceptable beyond ~20 pages.
- Post-v1 migration cost is real. If the docs grow significantly before the migration card is filed, refactoring the builder is extra work. The design doc explicitly caps v1 at 5 content pages to contain this risk.
- Docusaurus migration path preserved. The content manifest is
Markdown files in
docs/customer/. Any future framework can consume the same source files without content rewrites.
Alternatives considered
| Option | Rejected because |
|---|---|
| Docusaurus | Correct long-term choice but introduces Node/npm at T-8; adds risk without adding v1 value beyond 5 pages |
| VitePress | Stack mismatch (Vue); same new-dependency risk as Docusaurus |
| mkdocs-material | Python, but requires pip install of theme + plugins not currently in repo; new dependency at T-8 |
| Mintlify | Managed vendor; per-volume pricing; lock-in unacceptable for a platform surface we may need to customize |