Skip to content

feat!: add the quarto-definition-list describe format - #114

Merged
eitsupi merged 3 commits into
mainfrom
feat/quarto-definition-list
Nov 14, 2026
Merged

eitsupi merged 3 commits into
mainfrom
feat/quarto-definition-list

Conversation

@eitsupi

@eitsupi eitsupi commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

Summary

Add the quarto-definition-list describe format, which writes \describe{} lists as Quarto's ::: {.definition-list} div:

::: {.definition-list}

- `a`

  - The first value.

:::

Quarto 1.11.7+ and q2 render it as a <dl>. The default stays pandoc-definition-list; switching the default, and pointing the deprecated definition-list value at this format, are left for follow-ups.

Design

  • The mdast keeps the semantic DefinitionList node; only the syntax differs. WriterOptions gains definition_list_syntax (Pandoc by default, or QuartoDiv), and no new Node variant is added, so AST JSON and mdast consumers are unaffected beyond the new field.
  • DescribeFormat::definition_list_syntax() maps the describe format to the writer syntax in one place. It is used by the document writer and by Arguments cells, which are rendered during conversion.
  • Each div item is the term followed by a bullet list with one item per description, which is the shape Quarto and q2 require:
    • Several descriptions of one term stay separate nested items; Quarto 1.11 and q2 render each as its own <dd>.
    • An empty or missing description becomes &#8203;, so Quarto still recognizes the item.
    • A definition list without terms writes nothing.
  • Pipe-table cells keep flattening definition lists as before.

Also fixed

When a list item began with a nested list, the writer left the marker line empty and started the list on the next line. q2 rejects that form; the nested list now starts on the marker line (- - a). This shape is common in the new format (a description holding only a list). Output of the existing describe formats is unchanged on the man pages of several real packages (3558 files).

Verification

  • The describe fixture and edge cases (formatted term, empty description, empty term, description holding only a list, several paragraphs, inside a list-table cell, nested) rendered with Quarto 1.11.9 and q2 0.43 both produce the expected <dl> elements.
  • Converting the man pages of several real packages with this format gives 37 files containing the div. Both renderers produce one <dl> per div in 31 of them. q2 cannot render the other 6 because of unrelated quote parse errors (Q-2-7 / Q-2-11) that occur on main with the Pandoc format too.
  • Tests: writer exact-output cases for the div form, a describe inside Arguments cells, CLI snapshots for the new format, and config serialization.

Breaking changes

  • DescribeFormat gains QuartoDefinitionList.
  • WriterOptions gains definition_list_syntax; struct literals need the field or ..Default::default().

When a list item began with a nested list, the writer ended the marker
line empty and started the nested list on the next one. Pandoc and
CommonMark accept that, but q2 rejects an empty marker line followed by
a list. Write the nested list after the marker instead (`- - a`).
Add `DescribeFormat::QuartoDefinitionList` (CLI and config value
`quarto-definition-list`), which writes `\describe{}` lists as Quarto's
`::: {.definition-list}` div. Quarto 1.11.7+ and q2 render it as a
definition list.

The mdast keeps the semantic `DefinitionList` node; only the syntax
differs. `WriterOptions` gains `definition_list_syntax`, and the
describe format maps to it in one place, used both by the document
writer and by Arguments cells, which are rendered during conversion.

In the div form each item is the term followed by a one-item bullet
list with the description. Descriptions of one term are merged, an
empty description becomes a zero-width placeholder so Quarto still
recognizes the item, and a list without terms writes nothing.
Pipe-table cells keep flattening definition lists as before.
The Quarto div form merged all descriptions of one term into a single
nested item, so two `DefinitionDescription` nodes became two paragraphs
of one definition. Quarto documents several definitions of a term as
several nested items, and both Quarto 1.11 and q2 render each as its
own `<dd>`. Write one nested item per description.
@eitsupi
eitsupi merged commit a466df9 into main Nov 14, 2026
14 checks passed
@eitsupi
eitsupi deleted the feat/quarto-definition-list branch November 14, 2026 07:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant