The file is a document, not a form plus a data file.
A docc source file is ordinary Markdown preceded by YAML frontmatter. You can read it from top to bottom, edit it in any text editor, compare it in a diff and hand it to an author without teaching a template language.
--- docc: 1 document_type: ch_letter subject: Mahnung — Rechnung 2026-114 --- Sehr geehrte Frau Muster Wir vertreten die Muster Handels AG in der oben genannten Angelegenheit. # Aufforderung Wir fordern Sie hiermit auf:
The marker is intentional. Files without docc: 1 are not docc documents, so ordinary notes, READMEs or files from another Markdown tool are not accidentally treated as compiler input.
Put facts in frontmatter when they are facts, not prose.
The schema for the chosen document type declares the allowed frontmatter keys. Values can be strings, integers, booleans, dates, enums, lists and named compound types such as a sender or recipient address.
sent: 2026-08-05 registered: true sender: name: Muster & Partner uid: CHE-123.456.789 street: Musterstrasse 1 postal_code: "5000" city: Aarau beilagen: - Rechnung Nr. 2026-114 - Zahlungserinnerung
A schema can mark a field required, give it a default, permit an explicit null, constrain it with a pattern or enumerate its acceptable values. That is why a sentence can stay a sentence while the date, address and routing facts remain reliably checkable.
docc describe <type> before authoring an unfamiliar type. It is the compiler’s own explanation of what the frontmatter and body contract require.Use headings, lists and paragraphs as you already do.
Most documents need no special syntax in their body. The schema maps standard Markdown constructs to named theme styles and may declare a required heading hierarchy where structure matters.
# Ausgangslage Unsere Mandantin stellte Ihnen die Rechnung über CHF 8'400.— zu. # Aufforderung 1. den Betrag bis zum 31. August 2026 zu überweisen; 2. uns die Zahlung unaufgefordert zu bestätigen. > Der Schuldner einer Verbindlichkeit wird durch Mahnung des Gläubigers > in Verzug gesetzt.
A letter type may intentionally have no required body sections. A formal filing can insist on a sequence of headings and conditional subsections. The author sees the structure in the document; the schema decides when its absence is a defect.
Mark document semantics without hiding the wording.
There are two extensions for facts that plain Markdown cannot express. Both remain visible in source and both exist only when the schema declares their meaning.
Blocks: a structural region with attributes
::: partei {#verkaeufer kind=person role=veraeusserer} Herr [Max Muster]{.name}, geboren am [12. April 1975]{.geburtsdatum}, wohnhaft an der [Musterstrasse 10, 5400 Baden]{.adresse} :::
A block is a :::name region. Attributes are {#id key=value}; the schema can use a discriminator such as kind to select a permitted variant and state the spans that variant requires.
Spans: an inline, typed fact
Der Erwerber ist [Max Muster]{.partei ref=verkaeufer}.A span annotates literal text inline. It never replaces the author’s words with generated language; it lets a schema validate the fact, resolve a declared reference or apply a style according to the document type.
Keep intentional blanks distinct from missing information.
Sometimes a document must be compiled with a line left to complete by hand: a signature, a handwritten selection or an amount set at execution. That is content with a deliberate state, not a forgotten frontmatter value.
Ort und Datum: [________________]{.docc-field key=before_execution}
Unterschrift: [________________]{.docc-field key=signature}The reserved docc-field span marks that difference. A schema can constrain its permitted keys; check can accept an intentional blank while build can deliberately reject fields that must be completed before a final output exists.
Do not smuggle a second programming language into the document.
docc’s content model is intentionally narrow. Schemas describe document behavior through frontmatter, blocks, spans, fields, body structure and named rules. Layout belongs to a theme. Conditional template logic, a macro language and external data assembly are not authoring features.
For every accepted key and syntax detail, use the canonical authoring guide and schema reference.