Document Templates
updated
A project can define document templates — the web app calls them Document Types: a title, a description, and the Custom Fields a document of that kind is expected to fill in. A template has no body of its own; it decides a document’s fields, not its text. A document declares the template it follows with the template: frontmatter key, and the CLI syncs that key in both directions.
A project with no templates behaves exactly as before: nothing about templates appears anywhere.
Requires CLI 1.3.0 or newer and a server that supports templates. Against an older server the CLI degrades cleanly — see Older servers below.
Browse the project’s templates
meldoc templates list
adr Architecture Decision Record
* how-to How-To Guide
runbook Operational Runbook
* = project default (how-to)
The starred entry is the project default. meldoc templates show prints one template in full:
meldoc templates show adr
alias: adr
title: Architecture Decision Record
description: One decision, its context and its consequences
fields: status, decided-on
No skeleton: 'meldoc new --template adr' writes the key and an empty body.
fields lists the custom field keys the template carries. The last line is the CLI saying that a template has no body to seed.
With several projects configured, both subcommands need --project — the registry belongs to a project, and the same template alias may exist in more than one. See Several Projects in One Repository.
Create a document from a template
meldoc new --alias adr-0007-drop-redis --template adr
This writes template: adr into the frontmatter and leaves the body empty:
---
alias: adr-0007-drop-redis
title: adr-0007-drop-redis
template: adr
---
You can also add or change template: by hand in any document and push it.
How template: syncs
The key travels in both directions, and meldoc pull is authoritative about it:
- A document that has a template on the server gets the key written into the file.
- A document that has no template on the server gets the key removed.
Removal is deliberate: template has no default value to leave out, so the file states either the assignment or its absence, and nothing is hidden.
Expect frontmatter changes in documents you did not edit, the first time you pull against a server that has templates. How much at once depends on the pull. A full pull —
--force, or a fresh clone with no cursor — touches every document that has a template, so it lands as one large diff. An ordinary incremental pull does not: unchanged documents are not in the change set, so the key appears document by document as those documents happen to change. Most repositories see it trickle in — so if you are reviewing a diff and wondering where atemplate:line came from, this is where.
One consequence worth knowing: a hand-written template: naming an alias the project does not have is not accepted by the server. push warns and leaves the assignment alone, so the next pull deletes the line.
What validate checks
meldoc validate
Two template checks, both warnings:
| Warning | Meaning |
|---|---|
template: names an alias the project does not have |
Typo, or a template that was removed from the project |
Bare template: (YAML null) or a non-string value |
Reaches the server as nothing at all, while looking like it says something |
Neither can fail a push or a ci run, by design: the CLI runs over batches of hundreds of files and over repositories that predate the feature, so one typo in one document must not fail a whole publish. --skip-validate is irrelevant to templates for the same reason.
--strict does not change this. It escalates content findings — broken links, broken assets, an unresolvable replacedBy — and neither template check is one of those, so both stay warnings under every combination of flags.
Working offline
The registry is cached on disk, refreshed by meldoc pull and by meldoc templates list. That cache is what lets meldoc validate and meldoc new --template work with no network.
One file per project, since the registry belongs to a project:
| Config | Cache file |
|---|---|
Names a project (projectAlias, or an entry under baseDirs) |
.meldoc/cache/templates/<projectAlias>.json |
| Names no project at all | .meldoc/cache/templates.json |
The split matters beyond tidiness. A single shared file kept only the registry of whichever project pulled last, and every other project’s cache then failed its own identity check — which turned a loud “this cache is not yours” into a silent skip of every template check in the repository. A single-project config keeps the original path, so its cache survives the upgrade untouched.
When the server cannot be reached, templates list and templates show answer from the cache and say so, rather than presenting stale data as current:
(cached 2026-08-27 14:31 — server unreachable)
If the server is unreachable and no usable cache exists yet, the command asks you to pull first.
Older servers
If the server doesn’t support templates, meldoc templates says so and the template: key in your files is left untouched.
What’s next?
Document Types — Create and manage a project’s types in the web app.
Command Reference — Full reference for every CLI command.
Several Projects in One Repository — Several projects in one repository.