Markdown Syntax¶
Quillmark Markdown is a strict superset of CommonMark 0.31.2 with a small set of GitHub Flavored Markdown extensions and one declared deviation. If you already know CommonMark, you only need to learn what is on this page.
For the authoritative grammar, block-detection rules, normalization, and limits, see the formal Markdown specification.
Foundation¶
Body content (the prose after each card-yaml block, including any card) is parsed as CommonMark 0.31.2. Headings, emphasis, links, lists, code blocks, blockquotes, thematic breaks, and inline code all behave exactly as the CommonMark spec defines them.
For the conventional syntax of these elements, refer to:
- CommonMark spec — the base grammar.
- GFM spec — pipe tables and strikethrough.
Selected GFM extensions¶
Quillmark enables a small, stable subset of GFM:
| Feature | Syntax | Notes |
|---|---|---|
| Strikethrough | ~~text~~ |
Standard GFM rules; word-bounded delimiter runs. |
| Pipe tables | \| col \| col \| with alignment row |
Supports :---, :---:, ---: alignment. |
| Underline | <u>text</u> |
The single allow-listed raw-HTML tag (see the deviation below). |
Task lists, autolinks beyond CommonMark's, and other GFM features are not enabled.
Deviation from CommonMark¶
Raw HTML is not rendered, except <u>¶
CommonMark passes raw HTML through to the output. Quillmark recognises raw HTML syntactically (so it does not break paragraph structure) but discards every tag, with one exception: <u>…</u> renders as underline.
<u>This is underlined</u>, even <u>across word boundaries</u>.
<span style="color: red">This span is dropped entirely.</span>
<!-- HTML comments are also dropped -->
Why: Typst (the rendering backend) has no HTML renderer, and arbitrary HTML passthrough would create injection risks for downstream tooling. <u> is allowed because no CommonMark-native syntax covers arbitrary-range underline.
Consequences:
<br>,<br/>,<br />produce no output. Use a CommonMark hard break instead — two trailing spaces before a newline, or a trailing\before a newline.- HTML entities and embedded SVG are dropped.
- HTML comments do not appear in output.
Out of scope¶
The following are recognised by the parser (so they will not corrupt surrounding content) but produce no output in the current version:
- Images (
) — reserved for the asset-resolver integration. - Math (
$…$,$$…$$) —$is treated as a literal character. - Footnotes, task lists, definition lists — not supported.
Some constructs (like link titles) are accepted by the parser but may be dropped during rendering when the active backend has no target for them. Those losses are backend-specific — see each backend's documentation.
Structured data: card-yaml blocks¶
Quillmark carries structured data in card-yaml blocks, each followed by its Markdown prose body. The full block-detection rules — fence syntax, the blank-line rule, and the backtick escape hatch for literal code blocks — are in §4 of the spec.