Documentation Toolchain¶

This page consolidates platform decisions on diagram tooling, documentation platform architecture, and multi-repository documentation aggregation. It supersedes ADR-0010, ADR-0015, and ADR-0023, which are retained as archived references.

Diagram Toolchain¶

Decision: All architecture diagrams are authored in Mermaid. No Kroki container, no D2 renderer.

Rationale¶

Mermaid is rendered natively by ADO Wiki, GitHub, and MkDocs Material without any server-side component. D2 produces cleaner output but requires a running Kroki service (or native D2 binary) and adds operational overhead with no meaningful fidelity gain for homelab-scale diagrams. Keeping diagrams in Mermaid keeps the documentation pipeline dependency-free.

Guidelines¶

Diagrams live in .md files as fenced ```mermaid blocks.
Prefer flowchart LR for component diagrams; sequenceDiagram for protocol flows.
Do not commit pre-rendered PNG/SVG outputs for diagrams that can be expressed in Mermaid — renders are regenerated by the platform.
Exception: complex multi-layer network diagrams may be committed as SVG if Mermaid cannot represent the layout clearly.

Documentation Platform Architecture¶

Decision: ADO Wiki is the primary internal documentation platform. MkDocs Material generates the public-facing portfolio site from the archon-docs repository.

Two-Tier Model¶

Tier	Platform	Audience	Content
Internal	ADO Wiki	Platform team only	Runbooks, credential references, incident logs, operational state
External	MkDocs Material	Public portfolio	Architecture decisions, platform overview, sanitized diagrams

MkDocs Publication Pipeline¶

archon-docs is the source-of-truth repository. The build pipeline runs mkdocs build to generate a static site. Before publication, sanitize.py processes the docs/ directory into build/docs/, applying substitutions to remove internal hostnames, IP addresses, and credential references.

Sanitization Principles¶

Documentation destined for public publication (Tier 2 content in docs/architecture/, ADRs) must not contain:

Internal IP addresses or RFC 1918 ranges
Internal hostnames or node names
Credentials, tokens, or API keys
OT zone identifiers that would reveal physical layout

sanitize.py enforces these substitutions automatically. Authors should write documentation using canonical names (e.g., "the monitoring node") rather than internal hostnames when the audience is mixed.

Content Organization¶

docs/
  adr/          — Architecture Decision Records (classified in security/, it/, ot/ subdirs)
  architecture/ — Tier 2: public narrative, diagrams, topology (sanitized before publish)
  platform/     — Tier 3: operational runbooks, platform-specific guides (internal)
  reference/    — Tier 3: quick-reference tables, naming conventions (internal)
  runbooks/     — Tier 3: incident response, maintenance procedures (internal)
  internal/     — Tier 3: non-public guides (internal only)

Multi-Repository Documentation Aggregation¶

Decision: archon-docs aggregates documentation from multiple repositories. Device and firmware documentation lives in the source repository (archon-apps, firmware repos) and is pulled into archon-docs at build time via mkdocs.yml navigation references or the multirepo MkDocs plugin.

Aggregation Pattern¶

Source repo	Content location	Published under
`archon-apps`	`ot/docs/`	`devices/ot/` in archon-docs nav
Firmware repos	`docs/`	`devices/firmware/` in archon-docs nav

When a new repository is added that generates user-visible documentation, the procedure is:

Add a docs/ directory with an index.md to the source repo.
Add a nav entry to archon-docs/mkdocs.yml pointing to the remote path.
Ensure the source repo's mkdocs.yml (if standalone) uses compatible Material theme settings.

ADR Classification¶

ADRs are classified into three classes and eleven prefixes per the taxonomy defined in ADR-0047:

Class	Prefixes
`security/`	IAM, APPSEC, SECOPS, GOV, RISK
`it/`	PLAT, NET, OBS, DEV, LLMOPS
`ot/`	OT

New ADRs must be placed in the correct class subdirectory under docs/adr/. The AMEND-OR-CREATE-OR-WIKI decision tree (documented in CLAUDE.md and ADR-0047) must be applied before authoring any new ADR.

Sources¶

Retired ADR	Date	Content
ADR-0010 Mermaid over D2/Kroki	2026-03-31	Diagram toolchain decision
ADR-0015 Documentation platform	2026-04-02	ADO Wiki vs MkDocs; sanitization table
ADR-0023 Multi-repo docs aggregation	2026-04-06	Cross-repo documentation pull pattern