pampa - Unsupported definition lists in quarto-web change AST after a QMD round trip
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 54/100
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 - secondinitially becomes literal paragraphs, but the continuation reparses as a bullet list after writing. Rejecting Q-2-54 would also avoid this fallback path.   - itemparses without warnings asPara [Str " - item"], then writes as- itemand 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
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from quarto-dev/q2
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
quarto-dev/q2#1219 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
quarto-dev/q2#1188 · 3 comments ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 73/100
quarto-dev/q2#1179 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
quarto-dev/q2#1133 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
quarto-dev/q2#1103 · 1 comment ·
Maintainers usually reply within 1 day
Similar issues
-
priority: low
Difficulty 2/5 1-3 hours Newbie friendliness 67/100
storytold/photocraft#15350 ·
Maintainers usually reply within 1 day
-
area:davinci
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
ubugeeei-prod/vize#13167 ·
Maintainers usually reply within 1 day
-
area:ui enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
transit-audio/transit#738 ·
Maintainers usually reply within 1 day
-
enhancement good first issue help wanted
Difficulty 2/5 1-3 hours Newbie friendliness 91/100
hocinehacherouf/liberarr#78 ·
Maintainers usually reply within 1 day
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Maintainers usually reply within 1 day