Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đang mở
  • Có gì không ổn?
#905 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
3/5
Thời gian dự kiến
1-2 ngày
Mức phù hợp với người mới
54/100
Loại issue
Lỗi
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
rust
Lĩnh vực
backend, tooling

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.
Ngôn ngữ chính
Rust
Star
283
Fork
20
Merge trung bình
21 giờ 39 phút
Pull request đã merge (30 ngày)
157

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của quarto-dev/q2

Tất cả issue của quarto-dev/q2

Issue tương tự

Thêm issue về Rust

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.