docs-ssot

Appearance

Build Pipeline ​

Documentation Pipeline Architecture ​

This document describes how the documentation generation pipeline works.

Pipeline Overview ​

The docs-ssot system generates final documents (e.g., README.md, CLAUDE.md) from template files and modular Markdown sources.

The pipeline consists of the following stages:

  1. Template Loading
  2. Include Resolution
  3. Recursive Expansion
  4. Document Assembly
  5. Output Generation

Pipeline Flow ​

mermaid
flowchart TD
    A["template/docs/ (source markdown)"] --> B["template/*.tpl.md"]
    B --> C[Template Loader]
    C --> D[Include Resolver]
    D --> E{Include directive found?}
    E -- Yes --> F{Inside code fence?}
    F -- Yes --> G[Keep as literal text]
    F -- No --> H{Circular reference?}
    H -- Yes --> I[Error: circular include]
    H -- No --> J[Load included file]
    J --> D
    E -- No --> K[Document Builder]
    G --> K
    K --> L["README.md / AGENTS.md / CLAUDE.md"]

Step 1 — Template Loading ​

The system loads template files from the template/ directory.

Example:

template/README.tpl.md
template/AGENTS.tpl.md
template/CLAUDE.tpl.md

Templates define the structure of the final documents.

Step 2 — Include Resolution ​

Templates and Markdown files may contain include directives:

The following style is compatible with VitePress.

markdown
<!-- @include: docs/01_project/overview.md -->

The include resolver replaces this directive with the contents of the referenced file.

Step 3 — Recursive Expansion ​

Included files may also contain include directives.

The system resolves includes recursively until all includes are expanded.

A.tpl.md
→ includes B.md
→ includes C.md

Final result:

A + B + C

When each file is processed, relative Markdown links and image URLs are rewritten so they resolve correctly relative to the output file location rather than the source file location.

markdown
[docsgen.yaml](../../docsgen.yaml)

Step 5 — Document Assembly ​

After all includes are expanded, the document builder assembles the final Markdown document.

This includes:

  • Merging expanded content
  • Ensuring correct order

Step 6 — Output Generation ​

The final document is written to where defined at docsgen.yaml:

README.md
AGENTS.md
CLAUDE.md

These files are generated files and should not be edited directly.

Include Resolution Detail ​

The include resolver processes directives recursively. The following diagram shows the exact resolution algorithm:

mermaid
flowchart TD
    A[processFile called with path] --> B{Path in ancestor chain?}
    B -- Yes --> C[Error: circular include]
    B -- No --> D[Open file, add to ancestors]
    D --> E[Read next line]
    E --> F{Code fence toggle?}
    F -- Yes --> G[Flip inCodeFence flag]
    G --> H[Write line as-is]
    F -- No --> I{Include directive match\nAND not in code fence?}
    I -- No --> H
    I -- Yes --> J[Resolve include path]
    J --> K[Call processFile recursively]
    K --> L[Append expanded content]
    L --> M{More lines?}
    H --> M
    M -- Yes --> E
    M -- No --> N[Return assembled string]

Design Goals ​

The pipeline is designed with the following goals:

  • Single Source of Truth (SSOT)
  • Modular documentation
  • Reusable Markdown components
  • Template-based document generation
  • Deterministic document builds
  • Simple and predictable behavior