documator

A documentation CLI. This readme is itself rendered from templates/README.md into the repository root by the documator render command.

Install

uv sync

Usage

documator [--quiet] render INPUT_DIR OUTPUT_DIR [--watch] [--check] [--timeout SECONDS]
documator [--quiet] skills INPUT_DIR OUTPUT_DIR [--watch] [--timeout SECONDS]

render mirrors the input tree.

                                                                                
 Usage: documator render [OPTIONS] {input_dir} {output_dir}                     
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    input_dir       <parse>  [required]                                     │
│ *    output_dir      <parse>  [required]                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --watch                                                                      │
│ --check                                                                      │
│ --timeout        SECONDS  [default: root=10.0]                               │
│ --help                    Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯

--check renders the whole tree and writes none of it: nothing is created, overwritten or pruned. Every output that is missing, out of date, or still tracked after its template went away is reported, and the run exits non-zero — so CI can fail on a repository whose generated files have drifted from their templates without the job being able to paper over it. Blocks still run, since their output is what the comparison is about; --check bounds what documator writes, not what a template's commands do. It cannot be combined with --watch.

skills compiles the same templates into the flat <skill-name>/SKILL.md layout Claude's skill loader expects: nesting in the input tree is organisational only, the filename stem becomes the skill name, and the frontmatter is generated — any keys the template declares pass through, and a declared description wins over the name-derived placeholder.

An example tree might look like:

my-templates/
├── foo.md
├── bar/
│   └── SKILL.md
├── _hidden.md

and would result in:

.skills/
├── foo/
│   └── SKILL.md
├── bar/
│   └── SKILL.md

                                                                                
 Usage: documator skills [OPTIONS] {input_dir} {output_dir}                     
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    input_dir       <parse>  [required]                                     │
│ *    output_dir      <parse>  [required]                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --watch                                                                      │
│ --timeout        SECONDS  [default: root=10.0]                               │
│ --help                    Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯

Output

Every problem is logged where it arises and again at the end of the run, so a long render does not bury its errors above the scrollback. The run closes with a count — 12 files, 1 warning, 2 errors — followed by the warnings and then the errors, worst news nearest the prompt. Under --watch each recompile closes the same way, since a session has no other end to report at.

Log lines are coloured by level when stderr is a terminal, and plain when it is a pipe or when NO_COLOR is set. --quiet drops the per-file chatter and keeps warnings, errors and the summary; a quiet run that prints nothing is a run that had nothing to report.

Try it

mkdir -p docs/guides/plan/references out compiled
printf '# Review\n\nRead the diff before the description.\n' > docs/guides/review.md
printf -- '---\ndescription: Plan a change\n---\n# Plan\n' > docs/guides/plan/SKILL.md
echo '# Spec' > docs/guides/plan/references/spec.md
uv run documator render docs out
uv run documator skills docs compiled

Two layouts over one tree. render mirrors it into out/, so guides/review.md stays guides/review.md. skills flattens it into compiled/: the bare guides/review.md becomes review/SKILL.md with a name-derived description, and the guides/plan/ folder becomes plan/SKILL.md — carrying its declared description through — with references/spec.md bundled beside it as plan/references/spec.md.

This block is extracted verbatim and run by test_readme.py.