A schema says “valid.” A theme says “rendered.”
The author’s Markdown should not decide where the recipient address lands, which font a heading uses or whether a first-page header exists. Those are fixed layout decisions. Conversely, a theme should not be the only place that remembers a field is required or that an amount must match another value.
| Schema | Theme |
|---|---|
| Document contract Types, frontmatter shapes, heading structure, blocks, spans, fields and rules. | Document appearance Page geometry, styles, letterhead, frames, headers, footers, lists and formatting. |
| “A letter has a sender, recipient and subject; postal codes use this form.” | “The sender appears here; the recipient sits in this envelope window; this is the house font.” |
| Validated while checking source. | Validated against the schema before paragraph rendering begins. |
A profile pack is a small Git repository.
Profile packs keep schemas and themes together because they describe one organisation’s conventions. A manifest names the directories; the pack can be validated and versioned as a unit.
my-docc-profile/
├── docc-profile.yaml
├── schemas/
│ ├── _base.yaml
│ ├── ch_letter.yaml
│ └── ch_legal.yaml
└── themes/
├── _base.yaml
└── starter-letter.yamlThe built-in starter pack follows the same model. docc init copies it into an editable checkout so a team can begin from a real profile rather than a special-case template.
# Copy the built-in starter pack into the current project. docc init # Or install a Git-managed pack and bind it to this project. docc profile use ssh://git.example.ch/kanzlei/docc-profiles.git
Every build can say which profile it used.
When a project uses a pack, docc stores a project binding and lockfile. The selected revision—not whatever a remote repository happens to contain today—is what builds the document. Builds do not fetch or update profiles behind the author’s back.
docc profile status # Show the resolved source, reference and pinned commit. docc profile update # Resolve a newer revision; review and commit the lockfile change.
Resolution follows one shared order for schemas and themes: explicit directory flags, DOCC_PROFILE, a nearest project binding, a pack checkout, the user default, then the built-in starter. A missing or unusable explicit selection is an error, not permission to compile against an unrelated fallback.
Extend a base. Override deliberately.
Schemas and themes both support extends. The semantics stay aligned: maps merge key-by-key and ordered sequences are replaced wholesale when the child declares them. A child can change a small map entry without accidentally retaining half a parent list.
# schemas/ch_letter.yaml type: ch_letter extends: base theme: starter-letter frontmatter: subject: type: string required: true
Names beginning with _ are fragments: they can be extended but cannot be selected as a document type or theme. This gives a pack a place for shared defaults without exposing an incomplete profile as an authoring option.
The theme gets the last word on layout—after it proves it can render the type.
Before any paragraph is built, docc validates the fit between the schema and the theme: declared styles, interpolated fields and render-rule definitions must all resolve. This fails early instead of yielding a mostly-rendered Word document with a mysterious visual gap.
The writer creates the .docx archive directly, with no Word or template file in the rendering loop. It supports document furniture such as headers, footers, tables, images and positioned frames—the pieces a serious letterhead needs—while keeping their definitions in the profile rather than the source document.
Begin with the starter; make a pack when you own a standard.
Just writing a letter? Use the built-in example and theme. No profile setup is required to learn the workflow.
Adapting one office’s output? Run docc init, edit the copied starter pack and keep it with that project.
Sharing a maintained convention? Put the pack in Git, install it with docc profile use and commit the project lockfile.
Use the canonical profile packs, building profiles and theme reference documentation when you are ready to build a real pack.