add-syntax-construct

name

add-syntax-construct

description

Add a new block-level or inline-level syntax construct to Panache's parser and formatter — confirm the pandoc-native shape first, add SyntaxKinds for every byte category, gate it behind an extension or flavor, slot the block parser at the right precedence in the registry, teach the formatter, and pin it with fixtures in both golden suites. Use when asked to support a new Markdown/Quarto/Pandoc construct, or when a construct parses but formats wrongly because it was only half-wired.

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.

Step 4b — Inline-level constructs

Add a module under crates/panache-parser/src/parser/inlines/ and hook it into inlines/core.rs.

Check whether the surrounding dialect is already on the unified inline IR (inlines/inline_ir.rs) before choosing where to put the logic. The IR currently backs CommonMark only; the Pandoc dialect is mid-migration. Adding to the wrong side means the work is undone by the next migration step.

Step 5 — Typed AST wrapper

Add one in crates/panache-parser/src/syntax/ if the linter or LSP needs to interrogate the node. Consumers should never match on raw SyntaxKind sequences — that is what the wrappers exist to prevent.

Step 6 — Teach the formatter

Block dispatch is the match node.kind() in crates/panache-formatter/src/formatter/core.rs; inline handling lives in formatter/inline.rs.

An unhandled kind typically falls through to verbatim-ish output. That looks correct in a flat smoke test and breaks as soon as wrapping, indentation, or container nesting is involved — which is why step 7 insists on nested fixtures.

Step 7 — Fixtures in both suites

Both, not either:

• Parser golden case in crates/panache-parser/tests/fixtures/cases/<name>/ (input.md + optional parser-options.toml) pins the CST via insta and proves losslessness.
• Formatter golden case in tests/fixtures/cases/<name>/ (input.*, expected.*, optional panache.toml). Register the directory name in the golden_test_cases! macro at the bottom of tests/golden_cases.rs or it silently never runs.

Cover the construct nested inside a list item and inside a blockquote. Container prefixes are where most constructs break, and a top-level-only fixture will not catch it.

Step 8 — Verify

# Losslessness + idempotency on a real document using the construct
cargo run -- debug format --checks all scratch.qmd

# The real regression signal: a new block parser changes precedence globally
cargo test -p panache-parser --test commonmark
cargo test -p panache-parser --test pandoc

cargo test --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings

If a conformance suite regresses, the registry slot is the first suspect.

Step 9 — Document

Update the relevant page under docs/. If a config key was added, the schema regeneration from step 3 must be committed alongside.

Failure modes, in the order they usually appear

Symptom	Cause
Losslessness failure	A byte category has no SyntaxKind; markers folded into TEXT
Construct parses, output unchanged	Formatter match has no arm for the kind
Unrelated CommonMark examples regress	Registry slot too early, or the construct is not extension-gated
Breaks only inside a list or quote	No nested fixture; container prefix handling untested
Formatting is not idempotent	Formatter re-emits a marker the parser already captured