| 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.
- Add the flag to
Extensions in crates/panache-parser/src/options.rs.
- Wire the host-side default in
src/config.rs.
- 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
cargo run -- debug format --checks all scratch.qmd
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 |
