Roadmap: Docs as Code Reference
1. Overview
This roadmap defines the expansion of the Docs as Code reference from a core quick reference to a comprehensive documentation-as-code guide.
Current State |
Core reference with AsciiDoc basics, Antora patterns, and diagram syntax |
Target State |
Full reference comparable to official Asciidoctor docs, tailored to Domus ecosystem |
2. Current State (Phase 0 - Core)
The initial docs-as-code reference at Docs as Code covers:
-
AsciiDoc basics (headers, formatting, lists, admonitions)
-
Source code blocks with callouts
-
Tables with formatting options
-
Collapsible blocks
-
Cross-references (internal and cross-component)
-
Includes (partials, examples, tags, line ranges)
-
Diagrams: D2, Mermaid, PlantUML, Graphviz basics
-
Antora component structure
-
Build commands
3. Phase 1: Diagram-as-Code Deep Dive
3.1. Objectives
-
Comprehensive D2 reference (shapes, connections, styling, themes)
-
Mermaid advanced patterns (subgraphs, styling, themes)
-
PlantUML enterprise diagrams (architecture, deployment, state)
-
Graphviz layout control and clustering
-
Best practices for each diagram type
3.2. Tasks
| # | Task | Priority |
|---|---|---|
1.1 |
D2 complete syntax reference (all shapes, icons, SQL tables) |
HIGH |
1.2 |
D2 styling guide (themes, custom colors, typography) |
HIGH |
1.3 |
Mermaid flowchart, sequence, class, state diagram patterns |
MEDIUM |
1.4 |
PlantUML architecture diagrams (C4 model integration) |
MEDIUM |
1.5 |
Graphviz advanced layouts (rank, clusters, subgraphs) |
LOW |
1.6 |
Comparison guide: when to use which diagram tool |
MEDIUM |
3.3. Success Criteria
-
D2 reference matches d2lang.com/tour/intro depth
-
Mermaid reference covers all enterprise use cases
-
Real examples from domus-* repos included
4. Phase 2: AsciiDoc Advanced Patterns
4.1. Objectives
-
Document attributes and conditional content
-
Complex table patterns (nested content, AsciiDoc in cells)
-
Block types and custom styling
-
Includes with tag filtering and line ranges
-
Macro definitions and usage
4.2. Tasks
| # | Task | Priority |
|---|---|---|
2.1 |
Attribute inheritance and precedence |
MEDIUM |
2.2 |
Conditional content (ifdef, ifndef, ifeval) |
MEDIUM |
2.3 |
Complex table patterns (nested blocks, spans) |
HIGH |
2.4 |
Custom block styles and roles |
LOW |
2.5 |
Macro definitions for reusable content |
LOW |
2.6 |
Passthrough and raw HTML patterns |
LOW |
5. Phase 3: Antora Architecture Patterns
5.1. Objectives
-
Multi-repository aggregation patterns
-
Component versioning strategies
-
Navigation design patterns
-
Cross-component linking best practices
-
UI bundle customization guide
5.2. Tasks
| # | Task | Priority |
|---|---|---|
3.1 |
antora-playbook.yml comprehensive reference |
HIGH |
3.2 |
Multi-repo content source patterns |
HIGH |
3.3 |
Component versioning (semantic, date-based) |
MEDIUM |
3.4 |
nav.adoc design patterns for large sites |
MEDIUM |
3.5 |
UI bundle architecture (Handlebars, partials, helpers) |
LOW |
3.6 |
Extension points and supplemental UI |
LOW |