pampa - Unsupported definition lists in quarto-web change AST after a QMD round trip

Open
#905 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
54/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
rust
Domain
backend, tooling

Research direction

Start by tracing the Q-2-54 diagnostic and the QMD writer behavior described in the issue; the payload does not name source or test files. Reproduce the supplied typst-show.typ example with pampa, then check how changing Q-2-54 from a warning to an error affects parsing and diagnostics. Done means unsupported definition lists are rejected rather than accepted with a changed AST after writing and reparsing.

Written by the indexing model from the issue text.

Description

This surfaced while round-tripping existing quarto-web documents through q2r and pampa, including appendices.qmd, notebook-embed.qmd, and journals/templates.qmd. These documents use Pandoc-style definition lists. Pampa warns with Q-2-54 but accepts each definition as a paragraph containing its source text in a single literal Str. Writing and reparsing the accepted document changes that AST.

The writer escapes the leading colon, so the next parse treats the definition as ordinary paragraph text with separate words and spaces. Reparsing the emitted QMD produces no Q-2-54 warning, even though the definition has not been migrated to a supported definition-list representation. Definitions containing inline Markdown also lose that formatting during the initial fallback: in the excerpt below, the backticks around typst-template.typ become literal text, which the writer subsequently escapes. All three full documents reproduce the AST change and emit no Q-2-54 diagnostics when their written QMD is parsed again. The initial parse still emits the warning.

Getting the escaping correct seems a bit fraught so one possible option is to make Q-2-54 an error rather than a warning. That would reject these unsupported definition lists instead of accepting a literal-text fallback whose interpretation changes across the round trip. The diagnostic already identifies the supported ::: {.definition-list} form and the qmd-syntax-helper convert -r definition-lists migration command.

The following is the actual typst-show.typ entry from journals/templates.qmd, isolated from the rest of the document. It reproduces both the AST change and the escaping of literal backticks, without nested lists or character references.

Verified with pampa at d3ed54fe4dfc87750d7593ba9b40f974b725752f. Warning's location and hints are abbreviated with ... and Cargo status lines and ANSI color escapes are omitted.

$ printf -- 'typst-show.typ\n\n:   A show rule for the entire document that captures document metadata and passes it to the function defined in `typst-template.typ`.\n'
typst-show.typ

:   A show rule for the entire document that captures document metadata and passes it to the function defined in `typst-template.typ`.

$ printf -- 'typst-show.typ\n\n:   A show rule for the entire document that captures document metadata and passes it to the function defined in `typst-template.typ`.\n' | cargo run --bin pampa -- 2>&1
Warning: [Q-2-54] Pandoc definition lists are not supported
...

[ Para [Str "typst-show.typ"], Para [Str ":   A show rule for the entire document that captures document metadata and passes it to the function defined in `typst-template.typ`."] ]

$ printf -- 'typst-show.typ\n\n:   A show rule for the entire document that captures document metadata and passes it to the function defined in `typst-template.typ`.\n' | cargo run --bin pampa -- -t qmd 2>&1
Warning: [Q-2-54] Pandoc definition lists are not supported
...

typst-show.typ

\:   A show rule for the entire document that captures document metadata and passes it to the function defined in \`typst-template.typ\`.

The warning above comes from parsing the original input before writing QMD. Reading the emitted QMD separately produces the changed AST without a warning:

$ printf -- 'typst-show.typ\n\n\\:   A show rule for the entire document that captures document metadata and passes it to the function defined in \\`typst-template.typ\\`.\n' | cargo run --bin pampa -- 2>&1
[ Para [Str "typst-show.typ"], Para [Str ":", Space, Str "A", Space, Str "show", Space, Str "rule", Space, Str "for", Space, Str "the", Space, Str "entire", Space, Str "document", Space, Str "that", Space, Str "captures", Space, Str "document", Space, Str "metadata", Space, Str "and", Space, Str "passes", Space, Str "it", Space, Str "to", Space, Str "the", Space, Str "function", Space, Str "defined", Space, Str "in", Space, Str "`typst-template.typ`."] ]

Two additional probes exposed related writer behavior, but were not the original quarto-web failures:

  • A definition body containing : - first\n - second initially becomes literal paragraphs, but the continuation reparses as a bullet list after writing. Rejecting Q-2-54 would also avoid this fallback path.
  •   - item parses without warnings as Para [Str " - item"], then writes as - item and reparses as a bullet list. This character-reference case is independent of definition lists and would remain if Q-2-54 became an error but is also unlikely / self-inflicted.
Dominant language
Rust
Stars
302
Forks
22
Avg merge
5h 2m
Merged PRs (30d)
213

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from quarto-dev/q2

All issues in quarto-dev/q2

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.