Include Directives

Include Specification

This document defines the include directive specification used by docs-ssot.

Overview

The include directive allows Markdown files and templates to include other Markdown files. Includes are expanded recursively to build final generated documents.

---

Include Directive Syntax

<!-- @include: path [level=<delta>] -->

Example:

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

The directive must be written inside an HTML comment.

An optional level parameter adjusts the heading depth of the included content:

<!-- @include: docs/03_architecture/overview.md level=+1 -->
<!-- @include: docs/03_architecture/overview.md level=-1 -->
<!-- @include: docs/03_architecture/overview.md level=+2 -->

Parameter	Meaning
level=+1	Deepen all headings by one level (## → ###)
level=+2	Deepen all headings by two levels (## → ####)
level=-1	Shallow all headings by one level (### → ##)
level=0	No change (same as omitting the parameter)

Heading levels are clamped to the valid range [1, 6]. Headings inside fenced code blocks in the included file are not adjusted.

---

Supported Include Paths

The include directive supports multiple path formats.

1. Single File Include

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

Includes a single Markdown file.

2. Directory Include

<!-- @include: docs/02_product/ -->

Includes all .md files in the directory (non-recursive). Files are included in sorted filename order. The trailing / in the path is required to trigger directory mode. Subdirectories are skipped; only .md files directly in the specified directory are included.

3. Glob Include

<!-- @include: docs/02_product/*.md -->

Includes all files matching the glob pattern. Files are included in sorted (lexical) order. Glob metacharacters (*, ?, [) in the path trigger glob mode. If the pattern matches no files, no content is inserted (no error). Subdirectories matched by the pattern are skipped; only regular files are included.

---

4. Recursive Glob Include

<!-- @include: docs/**/*.md -->

Includes all files matching the recursive glob pattern. ** matches zero or more path segments, so docs/**/*.md matches both docs/file.md and docs/sub/deep/file.md. Files are included in sorted (lexical) path order. If the root directory does not exist or no files match, no content is inserted (no error). Directories are skipped; only regular files are included.

---

Include Order

When including multiple files (directory or glob), files are included in alphabetical order.

Recommended file naming:

01_overview.md
02_features.md
03_usecases.md

This ensures deterministic document structure.

---

Recursive Includes

Included files may contain include directives themselves.

Example:

A.md includes B.md
B.md includes C.md

Final expanded document:

A + B + C

The system expands includes recursively until no include directives remain.

The algorithm used for recursive resolution:

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]

---

Circular Include Detection

Circular includes are detected and treated as errors.

Example:

A.md includes B.md
B.md includes C.md
C.md includes A.md

This must result in an error.

---

Missing File Handling

If an included file does not exist, the generator must return an error and stop the build.

Includes must not fail silently.

---

Path Rules

• Paths are resolved relative to the file containing the directive
• Only .md files can be included
• Include directives must be on their own line
• Includes are expanded before document generation

---

Summary

Supported include formats:

Format	Description
file.md	Single file
dir/	All markdown files in directory
*.md	Glob include
**/*.md	Recursive glob include

Rules:

• Includes are expanded recursively
• Files are included in sorted order
• Circular includes are errors
• Missing files are errors
• Only Markdown files can be included