adf-codec/spec/flavour.md

The markdown flavour

The grammar of the extended markdown adfToMarkdown emits and markdownToAdf parses. Plain CommonMark is a subset: the flavour adds directives, never changes CommonMark meaning. The emitted form is contract (AGENTS.md §8). Per-node syntaxes build on this grammar in sections that follow (todo.md 1b–1c).

Canonical form

adfToMarkdown emits exactly one spelling; every CommonMark variant of the same document normalizes to it through the round-trip.

• Emphasis _em_, strong **strong**; * replaces _ only where _ cannot parse (intra-word).
• Bullet lists - , two-space continuation indent. Ordered lists incrementing 1. 2. 3., the first number taken from the node's order attribute.
• ATX headings (# … ######); setext input normalizes to ATX.
• Code fences ``` with the node's language as info string, the fence lengthened past any backtick run in the content; indented-code input normalizes to fences.
• Thematic break ---.
• Hard break: backslash at end of line (survives editors that trim trailing spaces).
• Links [text](url); <…> around a destination containing spaces; title in double quotes; <url> autolink when the link text equals its destination.
• Paragraphs on one line — no soft wrapping; soft line breaks in input collapse per CommonMark.
• Entity references in input decode to their characters; output backslash-escapes only where text would otherwise parse as syntax.
• Blocks separated by one blank line, no trailing whitespace, single trailing newline.

Directives

One grammar for everything CommonMark lacks. Names are the ADF node names (camelCase).

Inline: :name[content]{attrs}. [content] is inline markdown; each node's section says whether content and attrs are required. : opens a directive only when the name is followed immediately by [ or { — anything else (10:30, :smile:) is literal text.

Container block:

:::name arg {attrs}
block content
:::

The fence is three or more colons. arg is one optional bare token whose meaning each node defines (e.g. the panel type). The body is block markdown. The closing fence is a line of at least the opening's length, and a container's fence is longer than every directive fence line in its body, so closers are unambiguous — the code-fence rule. Canonical form uses minimal lengths.

Leaf block: ::name {attrs} — a block-position node with no body.

Attributes: {key=value key2="two words"}. A bare value matches [A-Za-z0-9_-]+; anything else is double-quoted with \" and \\ as the only escapes. All values are strings at the grammar level; each node's section assigns types. Canonical form orders keys alphabetically and spells values bare wherever allowed.

Escaping: the emitter backslash-escapes a : whose text would otherwise parse as a directive; a backslash before : in input always yields a literal colon.

The opaque carry (AGENTS.md §3)

A node type the library does not know rides as its raw JSON and restores to a deep-equal node:

• Block position: a fenced code block with info string adf, body = the node's JSON, serialized canonically — two-space indent, object keys sorted.
• Inline position: :adf{json="…"}, same serialization, quote-escaped.

The info string adf is reserved: a genuine codeBlock whose language is exactly adf is itself emitted through the opaque carry, so the reservation stays absolute and stays lossless.

Raw HTML in input

CommonMark input may contain raw HTML. markdownToAdf routes each construct through the foreign HTML element mapping (AGENTS.md §3; specified with the HTML dialect, todo.md milestone 6) — ADF has no raw-HTML node, so a construct without a mapping, comments and processing instructions included, is an error result naming it. The flavour never emits raw HTML.