The product promise

A successful build means more than “Word opened it.”

docc treats a document type as a contract. It parses authored Markdown, verifies the declared requirements, then renders through the selected theme. Validation gates rendering.

One clear boundary

Author the content. Declare the rules. Compile the result.

A Word file can contain an absent recipient address, an old placeholder, a heading in the wrong place or a legal value that does not match its required form. Those are document failures, not formatting preferences. docc moves that knowledge into a schema where it can be checked consistently.

AUTHOREDSourceMarkdown and YAML remain visible, reviewable and editable.
DECLAREDSchemaThe type says which facts and structures are valid.
SELECTEDThemeThe profile says how a valid type is rendered.
PRODUCEDOutputA .docx exists only after the source passed its checks.
What docc does not do: it does not invent missing facts, converse about the text, store documents or turn a template into an application. The input is an authored document; the product is a checked compilation.
Verification layers

Requirements are checked where they belong.

The selected schema decides the valid shape of one document type. The compiler checks the source against that shape and runs the type’s declared rules. The exact requirements are profile-specific; these are the kinds of guarantees a type can make.

LayerQuestion it answersExample
Document marker and typeIs this actually a docc document, and which contract applies?docc: 1 and document_type: ch_letter select a known type.
Frontmatter schemaAre required values present, typed and well-formed?A Swiss postal code must be four quoted digits; an enum must be one allowed value.
Body structureDoes the document contain the required headings in the expected order?A legal type can require RECHTSBEGEHREN before BEGRÜNDUNG.
Semantic markupAre declared blocks, spans and intentional blanks used correctly?A party block can require a name, date of birth and address span.
Named rulesDo type-specific cross-document constraints hold?A no-placeholder rule prevents [Name] from surviving to output.
Schema/theme fitCan the chosen theme render the schema’s declared styles and references?A missing theme style is rejected before a paragraph is emitted.

The compiler runs checks as a collection, not a queue of failures. An author should be able to correct all reported problems in a single editing pass.

Useful failure

Every error explains its place and its fix.

Diagnostics have a stable code, a source position and a hint. That makes the same result useful in a terminal, an editor, CI or an automated drafting loop.

brief.md:8:13: error[DOC010]: field `case_ref`
has malformed value "ZG2026000"
  |
8 |   case_ref: "ZG2026000"
  |             ^^^^^^^^^^ court reference in the form AA.YYYY.NNN,
  |                        e.g. "ZG.2026.000"

The code is stable. A workflow can identify the class of failure without scraping prose.

The caret is in source. The author repairs the Markdown file, rather than manually patching a generated Word document.

The hint is actionable. The expected form belongs beside the error rather than in someone’s memory.

Use the compiler

One document contract, several useful surfaces.

The build path is deliberately small. Each command exposes a different view of the same underlying document and profile.

# Validate without creating output.
docc check brief.md

# Build validates first, then emits the Word document.
docc build brief.md

# Machine-readable contract and diagnostics for tools, agents or CI.
docc describe --json ch_letter
docc check --json brief.md

# Inspect the document's parsed facts and structure as JSON.
docc read brief.md

# Serve the same diagnostics while typing.
docc lsp

check --json emits a result object containing ok, error and warning counts, and diagnostics. The JSON command contract keeps stdout structured so another tool can consume it without parsing decorative terminal output.

Repeatable result

Same inputs, same document bytes.

docc emits the .docx itself. With unchanged source, schema and theme, the generated archive is byte-identical regardless of machine, clock or network. The document records its profile provenance; incidental environment state does not leak into the output.

Why that matters for a letter: a rebuilt version is not “probably the same.” If its bytes changed, a source or profile input changed. This turns document generation into something reviewable and reproducible instead of a last-mile manual ritual.

For the full model, read the project’s philosophy and the schema reference.