Add Syntax Construct

Use this skill when adding syntax Panache does not yet understand, or when finishing a construct that was wired into the parser but not the formatter.

This is the most error-prone change in the codebase. Skipping a step here does not fail loudly at the point of the mistake — it surfaces later as a losslessness failure, a silently unformatted node, or a global precedence regression in a conformance suite.

Scope boundaries

• Not for lint rules. Use the add-lint-rule skill.
• Not for conformance triage. If the goal is "make example N pass", use commonmark-conformance or html-conformance instead — those start from a failing case, not from a construct.
• Not for inline IR migration. Moving an existing Pandoc inline onto the unified IR is pandoc-ir-migrate.

Step 1 — Confirm the pandoc-native shape first

Pandoc's AST decides what the CST must be able to express. Do not design the CST from the surface syntax alone.

printf '<your construct>' | pandoc -f markdown -t native
printf '<your construct>' | cargo run -- parse --to pandoc-ast

The second command prints the same shape as the first, so divergences diff directly. Note what pandoc nests and what it flattens — that is the structure the CST has to support, even if the surface syntax looks flat.

If the construct is Quarto- or MyST-specific and pandoc does not know it, find the closest pandoc construct it degrades to, and check assets/pandoc-spec/.

Step 2 — Add SyntaxKind variants

In crates/panache-parser/src/syntax/kind.rs, SCREAMING_SNAKE_CASE.

Add a distinct kind for every byte category you need to round-trip: the marker, the delimiters, the content, and any attribute payload. A construct that reuses TEXT for its markers cannot be formatted without re-lexing later, which is the usual reason a construct ends up needing a second pass.

Step 3 — Gate it behind a flag

New syntax almost always belongs to an extension or a flavor.

1. Add the flag to Extensions in crates/panache-parser/src/options.rs.
2. Wire the host-side default in src/config.rs.
3. Set it per flavor.

A construct that is unconditionally live changes behavior for commonmark and will break that conformance suite. This is not optional.

If the flag adds a config key, regenerate the schema: UPDATE_EXPECTED=1 cargo test config_schema.

Step 4a — Block-level constructs

Add a module under crates/panache-parser/src/parser/blocks/ exporting try_parse_*() / emit_*(). Implement BlockParser in crates/panache-parser/src/parser/block_dispatcher.rs and insert it into the BlockParserRegistry::new() vector.

Registry order is precedence. The vector is deliberately aligned with pandoc's reader order, documented in a doc comment on the registry citing pandoc/src/Text/Pandoc/Readers/Markdown.hs:487-515. Placing a parser in the wrong slot is the single most common cause of subtly wrong output. Existing load-bearing constraints, each with a comment at its entry:

• fenced code must precede YAML metadata
• MyST directives must precede fenced code (brace-tagged opener wins)
• close-parsers precede their open-parsers (fenced divs, MyST directives)
• headings must precede horizontal rules
• admonitions must precede indented code (4-space body would be eaten)
• indented code must follow fenced code

Justify your position in a comment next to the entry, as the existing ones do.

detect_prepared() may return a payload (Box<dyn Any>) that parse_prepared() consumes, so emission never re-parses. Use it instead of scanning the line twice — re-scanning in emission is the quiet path back to two-pass parsing.