Organisation-wide standards

Keep the rules and the stationery in the same place.

A profile pack contains schemas and themes. It is the versioned, explicit answer to two questions: what counts as a valid document here, and what should that valid document look like?

A clean split

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.

SchemaTheme
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.
The practical result: changing a letterhead does not require touching every letter. Adding a required document fact does not require a Word template scavenger hunt.
The unit of distribution

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.yaml

The 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
No silent fallback

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.

Provenance is part of output. The generated document records the profile source and revision that produced it, making the rendering decision inspectable later.
Share without copying

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.

Render after validation

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.

Choose the smallest next move

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.