Concepts¶
How Quillmark separates concerns¶
Quillmark separates content, schema, and presentation:
- A Quill's schema drives the data: it validates the card-yaml metadata and applies coercion, defaults, and scaffolding. The schema is the contract every render consumes.
- A Quill's plate controls presentation: it defines layout and typesets the output artifact.
- Markdown provides content: authors write plain Markdown with card-yaml blocks; the Quill renders it into a fully typeset document.
Core Components¶
Quill Formats¶
A Quill is a format bundle that defines how Markdown content should be rendered. It contains:
- Metadata (
Quill.yaml) - Configuration including name, backend, and field schemas - Plate file - Backend-specific plate that receives document data as JSON
- Assets - Fonts, images, and other resources needed for rendering
card-yaml Blocks¶
Quillmark documents use card-yaml blocks to provide structured metadata. A
card-yaml block is delimited by bare ~~~ / ~~~ fences and may begin
with a run of $-prefixed system metadata lines followed by a YAML payload.
(~~~card-yaml is also accepted as a non-canonical alias; the
canonical opener is a bare ~~~. To write a literal fenced code block in
prose, use a backtick fence or a ~~~ fence with a language info string:
adding more tildes does not escape, as a ~~~~ block is still a card.)
~~~
$quill: my_format
$kind: main
title: My Document
author: John Doe
date: 2025-01-15
~~~
# Content starts here
This metadata is accessible in formats and is validated against native schema rules defined in the Quill. See card-yaml Blocks for the full syntax.
Backends¶
A backend compiles a quill's backend-specific inputs plus injected JSON data into the final artifact. Quillmark ships two backends:
| Backend | Reads | Produces |
|---|---|---|
| Typst | a plate | PDF, SVG, and PNG; fields declared type: richtext are lowered to Typst markup during compilation |
| pdfform | a stripped PDF background and field spec, instead of a plate | an existing PDF form with its fields filled directly |
Required $quill Metadata¶
Each document must declare its target format in the root block's $quill system metadata line. If missing, parsing fails. Quill names must be snake_case ([a-z_][a-z0-9_]*); hyphens are not allowed.
The Rendering Pipeline¶
Quillmark follows a three-stage pipeline:
- Parse & Normalize - Extract card-yaml blocks and body prose; apply schema coercion/defaults, strip bidi characters, fix HTML fences. Absent fields are zero-filled in the backend projection (never persisted): partial documents are always renderable.
- Compile - Backend receives plate content + JSON data and converts them into final artifacts (PDF, SVG, PNG, etc.)
- Output - Return artifacts with metadata