Markdown definition lists, tested with pandoc

You typed a term, put its meaning on the next line after a colon, and got back one paragraph with a stray colon in the middle. Pandoc's commonmark reader did exactly that in this test.

A markdown definition list pairs a term with one or more definitions. Results here come from one test run on pandoc 3.8.3 under macOS, across three routes: plain CommonMark, pandoc's definition_lists extension, and a raw HTML block. Each result names the test file it came from, so you can rebuild the file and run the same command.

What plain CommonMark does

No definition list syntax appears in CommonMark 0.31.2. Searching the spec text for the phrase "definition list", ignoring case, matched no line. The same search for "block quote", run as a control, matched 57 lines.

Here is the first test file, dl-basic.md:

Jane Doe
:   Owner of Doe Holdings.

Feeding the file into pandoc -f commonmark -t html dl-basic.md gave one paragraph:

<p>Jane Doe : Owner of Doe Holdings.</p>

The colon line didn't start a new block. Pandoc kept it in the same paragraph as the term, and the colon came out as text. A ~ line in place of the colon line gave the same kind of paragraph, as Blank lines, markers and spacing shows.

The definition_lists extension

Pandoc has an extension named definition_lists. The --list-extensions option marks an extension with a + for on or a - for off. For this run, pandoc --list-extensions=markdown | grep definition_lists printed +definition_lists, and pandoc --list-extensions=commonmark | grep definition_lists printed -definition_lists.

Adding a flag to the reader name changes that. These three runs used the same dl-basic.md file:

• pandoc -f commonmark+definition_lists -t html dl-basic.md gave a <dl> element.
• pandoc -f markdown -t html dl-basic.md printed that <dl> element too, with no flag.
• pandoc -f markdown-definition_lists -t html dl-basic.md gave <p>Jane Doe : Owner of Doe Holdings.</p>, the same paragraph as the plain commonmark reader.

The first of those runs printed this:

<dl>
<dt>Jane Doe</dt>
<dd>
Owner of Doe Holdings.
</dd>
</dl>

The term became a <dt> element and the colon line became a <dd> element. For this file, the result followed the extension setting in both readers.

Write a definition list with pandoc

The test file dl-multi.md holds two terms. Here's how to build one like it and check it.

1. Put the term on a line of its own, such as Jane Doe.
2. On the next line, type a colon, three spaces and the definition, as in : Owner of Doe Holdings. from the test file.
3. To give the same term a second definition, add another colon line right under the first one.
4. Before the next term, add an empty line, then write it the same way.
5. Test it with pandoc -f commonmark+definition_lists -t html dl-multi.md, swapping in the name of your file for dl-multi.md, and look for <dt> and <dd> in the output.

The test file looks like this:

Jane Doe
:   Owner of Doe Holdings.
:   Signs the plans.

John Doe
:   Reviews the plans.

Pandoc gave one <dl> holding two <dt> elements. Jane Doe got two <dd> elements, one per colon line, and John Doe got one. The markdown reader gave the same output with no flag.

If your output shows a <p> with the colon still in it, check two things the tests on this page touch: the reader flag, and the space after the colon.

Blank lines, markers and spacing

Five small test files probe the edges of the extension. In each one, commonmark+definition_lists and markdown gave the same output.

An empty line after the term

The file dl-loose.md puts a blank line between the term and the colon line:

Jane Doe

:   Owner of Doe Holdings.

With the extension on, pandoc wrapped the definition in a <p> inside the <dd>. In dl-basic.md, with no blank line, the <dd> held bare text. The plain commonmark reader gave two paragraphs: <p>Jane Doe</p> and <p>: Owner of Doe Holdings.</p>.

Two definitions for one term

This is the dl-multi.md case from the steps above. Each colon line under a term became a separate <dd>. Without the extension, the commonmark reader joined the term and both colon lines into one paragraph.

A tilde in place of the colon

The file dl-tilde.md uses ~ Owner of Doe Holdings. as the definition line. With the extension on, pandoc gave the same <dl> as dl-basic.md. The commonmark reader gave <p>Jane Doe ~ Owner of Doe Holdings.</p>.

A second paragraph in the definition

The file dl-twopara.md adds an indented line after a blank line:

Jane Doe
:   Owner of Doe Holdings.

    Second paragraph of the definition.

With the extension on, pandoc put both lines in the same <dd>, with no <p> tags around either one. Without it, the commonmark reader turned the indented line into a <pre><code> block. For more on indents that turn text into code, see code from an indent.

Text right after the colon

The file dl-nospace.md uses :Owner of Doe Holdings. with nothing between the colon and the text. Here the extension made no difference. The commonmark run, the commonmark+definition_lists run and the markdown run each gave <p>Jane Doe :Owner of Doe Holdings.</p>.

A raw HTML block

The third route writes the list as HTML. Tag names that can start an HTML block in CommonMark 0.31.2 include dd, dl and dt (spec lines 2232 to 2244). That kind of block ends at a line followed by a blank line (spec line 2245). For the blank-line rule and how a viewer may treat HTML, see the post on raw HTML; this section sticks to the test.

The file dl-html.md holds four lines:

<dl>
<dt>Jane Doe</dt>
<dd>Owner of Doe Holdings.</dd>
</dl>

Passing it to pandoc -f commonmark -t html dl-html.md returned those four lines unchanged. The markdown reader kept the same tags too, but put Jane Doe and Owner of Doe Holdings. on lines of their own.

Markdown inside those tags is a separate question. A second file, dl-html-bold.md, wraps the word Owner in double asterisks:

<dl>
<dt>Jane Doe</dt>
<dd>**Owner** of Doe Holdings.</dd>
</dl>

Both pandoc -f commonmark -t html dl-html-bold.md and pandoc -f commonmark+definition_lists -t html dl-html-bold.md returned the block unchanged. The asterisks stayed as text, and no <strong> element appeared. If a definition needs bold or a link, test that exact file first, with the reader you plan to use.

To see which route your own file is on, run pandoc on it twice, once with +definition_lists added to the reader name and once without, and compare the two outputs. A <dl> in one and a <p> in the other tells you the extension is doing the work. For lining up terms and values in rows and columns, the tables guide shows the other format to test.

Where Sashmark fits

Fixing text right on a file's rendered page is part of the Sashmark v1 plan, with untouched lines planned to keep their original bytes through a clean Round-Trip. The plan also adds a Changes View, meant to flag edits since your previous visit to that file and planned to need no git. It is in development and has not been released. The app itself has no AI features. See the planned features, the help pages and the roadmap for where each part stands.

Check sashmark.com for updates.