Context
We use ciderpress for a docs site and maintain a set of templates under docs/_templates/ (adr, concept, guide, runbook, prd, rfc, etc.). To make templates fillable by both humans and AI agents, we've adopted a convention inside each template:
{{ like this }} — a blank the author must fill in (the text names what goes there).<!-- comments --> — HOW-to-write guidance that should be deleted before publishing.- Plain
## headings — structural, kept as-is.
Today ciderpress draft --type <type> --title <title> --out <dir> scaffolds a file from the matching template but only substitutes the title. Everything else is left to manual find-and-replace, and nothing stops a half-filled draft (leftover {{ }} or guidance comments) from shipping.
Ask
- Variable substitution at draft time. Resolve a known set of vars when scaffolding:
{{title}}, {{date}} (ISO, for our YYYY-MM-DD-slug.md record naming), {{slug}}, {{author}} (from git config), {{filename}}.
- First-class
{{ }} placeholder convention. Treat {{ ... }} as fill-me markers: after draft, print the remaining placeholders as a checklist; and provide a ciderpress check/lint that fails when a committed doc still contains {{ }} markers (or, optionally, leftover guidance comments).
- Optional
--clean flag to strip HTML guidance comments from the scaffolded output.
Why
Docs are authored by humans and increasingly by coding agents. A machine-parseable "what must I fill?" signal plus validation ("no {{ }} may remain in a published doc") turns a loose convention into something the tool enforces — no more half-filled templates slipping through review.
Happy to contribute a PR if this direction sounds right.
Context
We use ciderpress for a docs site and maintain a set of templates under
docs/_templates/(adr, concept, guide, runbook, prd, rfc, etc.). To make templates fillable by both humans and AI agents, we've adopted a convention inside each template:{{ like this }}— a blank the author must fill in (the text names what goes there).<!-- comments -->— HOW-to-write guidance that should be deleted before publishing.## headings— structural, kept as-is.Today
ciderpress draft --type <type> --title <title> --out <dir>scaffolds a file from the matching template but only substitutes the title. Everything else is left to manual find-and-replace, and nothing stops a half-filled draft (leftover{{ }}or guidance comments) from shipping.Ask
{{title}},{{date}}(ISO, for ourYYYY-MM-DD-slug.mdrecord naming),{{slug}},{{author}}(from git config),{{filename}}.{{ }}placeholder convention. Treat{{ ... }}as fill-me markers: afterdraft, print the remaining placeholders as a checklist; and provide aciderpress check/lint that fails when a committed doc still contains{{ }}markers (or, optionally, leftover guidance comments).--cleanflag to strip HTML guidance comments from the scaffolded output.Why
Docs are authored by humans and increasingly by coding agents. A machine-parseable "what must I fill?" signal plus validation ("no
{{ }}may remain in a published doc") turns a loose convention into something the tool enforces — no more half-filled templates slipping through review.Happy to contribute a PR if this direction sounds right.