Docs Ssot

docs-ssot: Documentation SSOT Setup

This skill migrates existing Markdown documentation into a modular Single Source of Truth (SSOT) structure managed by docs-ssot, then builds and validates the output.

When to use this skill

• Setting up docs-ssot in a new or existing repository (follow the main Workflow)
• Adding a new generated output file (e.g., SETUP.md) to an existing SSOT structure (follow Adding a new output file)
• Regenerating documentation after editing source templates (run docs-ssot build)

Quick Command Reference

Workflow

Step 1 — Check prerequisites

Verify required tools are installed:

docs-ssot version   # docs-ssot itself
jq --version        # required by the generated-file protection hook
yq --version        # required by the generated-file protection hook and lefthook check

Install docs-ssot if missing:

# Homebrew (macOS/Linux)
brew tap hiromaily/tap && brew install docs-ssot

# or Go install
go install github.com/hiromaily/docs-ssot/cmd/docs-ssot@latest

Step 2 — Check if already migrated

Before running migration, check whether this repository already has a docs-ssot structure:

ls docsgen.yaml 2>/dev/null
ls template/sections/ 2>/dev/null

If both exist, the repository is already (partially or fully) migrated. Do not run docs-ssot migrate on generated output files. Instead, skip to Step 5 to review the structure, or Step 8 to validate the current state.

If docsgen.yaml does not exist, or template/sections/ is empty or missing, proceed with Steps 3–6.

Step 3 — Identify existing documentation files

List Markdown files in the repository root:

ls *.md

Common candidates: README.md, CLAUDE.md, AGENTS.md, SETUP.md, ARCHITECTURE.md

Do not migrate files that are already outputs in docsgen.yaml — migrating a build artifact instead of a source file will produce incorrect results.

Step 4 — Preview and run the migration

First, preview without writing files:

docs-ssot migrate --dry-run README.md CLAUDE.md

Review the output to understand how sections will be categorised and which are detected as duplicates. Then run the actual migration:

docs-ssot migrate README.md CLAUDE.md AGENTS.md

This will:

1. Split each file by H2 headings into section files under template/sections/<category>/
2. Create template files under template/pages/ with @include directives
3. Create or update docsgen.yaml with build targets
4. Verify round-trip: build and compare output against originals

docsgen.yaml reference (the file created/updated by migration):

index:
  output: template/INDEX.md   # optional: generates include-relationship index

targets:
  - input: template/pages/README.tpl.md
    output: README.md
  - input: template/pages/CLAUDE.tpl.md
    output: CLAUDE.md

Add or remove targets to control which files are generated.

Step 5 — Review generated structure

docs-ssot index

Inspect:

• template/sections/ — modular section files (edit these, not the generated outputs)
• template/pages/*.tpl.md — template files defining document structure
• docsgen.yaml — build targets mapping templates to output files

Step 6 — Audit for duplicate content

Run this before creating any new section file. The docs-ssot migrate command deduplicates across the files it processes, but any additional content you create manually must be checked:

docs-ssot check

Also inspect existing sections:

ls template/sections/

Rule: If content for a new section already exists in a section used by another template (e.g., installation-guide.md already covers prerequisites and setup), do not create a duplicate. Instead, have the new template include the existing section:

<!-- template/pages/SETUP.tpl.md -->
<!-- @include: ../sections/development/installation-guide.md -->
<!-- @include: ../sections/development/setup-release.md -->

Only create a new section file when the content is genuinely new and not covered anywhere else.

Step 7 — Heading level convention

All section files under template/sections/ must start at heading level 2 (##).

## My Section Title       ← ✅ correct

# My Section Title        ← ❌ wrong

Why: Section files are embedded into larger documents where # is reserved for the document title. Starting at ## means most includes need no level parameter.

Exception — when a section file is used as a standalone output (e.g., .claude/rules/*.md), use level=-1 in the template to shift ## → #:

<!-- @include: ../sections/ai/rules/docs.md level=-1 -->