docs-ssot

Appearance

System Design ​

System Architecture ​

docs-ssot is composed of three main layers:

  1. Generator CLI (docs-ssot)
  2. Markdown source files (docs/)
  3. Template files (template/)

The generator reads template files, resolves include directives, and produces final documents such as README.md and AGENTS.md, CLAUDE.md.

docs-ssot CLI Core Components ​

Internally, the generator is intentionally simple and built around three core components:

1. Template Loader ​

Responsible for loading template files.

  • Reads template files from the template directory
  • Provides template content to the include resolver

Templates define the structure of generated documents.

2. Include Resolver ​

Responsible for resolving include directives.

  • Parses include directives
  • Loads referenced Markdown files
  • Expands includes recursively
  • Supports directory and glob includes
  • Detects circular includes
  • Returns fully expanded Markdown content

This is the core component of the system.

3. Link Path Rewriter ​

Responsible for rewriting relative links and image URLs in processed files.

  • Adjusts link paths to be correct relative to the output file location
  • Handles both Markdown links and image references
  • Ensures links work regardless of source file depth

4. Document Builder ​

Responsible for generating final output files.

  • Receives expanded Markdown content
  • Assembles the final document
  • Writes output files (e.g., README.md, AGENTS.md, CLAUDE.md)
  • Ensures deterministic output

Components ​

docs/ ​

The docs directory contains the Single Source of Truth Markdown files. Each file represents a small, reusable piece of documentation.

These files should:

  • be small
  • be reusable
  • contain only one topic
  • not depend on document structure

template/ ​

Template files define document structure.

They do not contain actual documentation content, only structure and include directives.

Examples:

  • README.tpl.md
  • CLAUDE.tpl.md

Templates decide:

  • document order
  • document sections
  • which content appears in which output

Generator (docs-ssot) ​

The generator is a CLI tool that orchestrates the core components:

  1. Load template (Template Loader)
  2. Resolve includes (Include Resolver)
  3. Write output (Document Builder)

docsgen.yaml Config file ​

Configuration for input file and output file.

yaml
targets:
  - input: template/README.tpl.md
    output: README.md

  - input: template/AGENTS.tpl.md
    output: AGENTS.md

  - input: template/CLAUDE.tpl.md
    output: CLAUDE.md

Document Build Flow ​

The document generation flow works like this:

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"]

Design Principles ​

The system is designed with the following principles:

  • Single Source of Truth
  • Modular documentation
  • Template-based composition
  • Generated outputs
  • Documentation as code
  • Deterministic builds
  • Simple implementation
  • No heavy static site generator

Design Philosophy ​

docs-ssot is intentionally minimal.

Instead of implementing a full template engine, the system performs only four operations:

  1. Load templates
  2. Expand includes (with heading level adjustment)
  3. Rewrite relative link paths
  4. Write documents

Everything else is handled through Markdown structure and file organization.