---
title: "Markdown definition lists, tested with pandoc"
slug: markdown-definition-lists
excerpt: "The section The definition_lists extension shows pandoc turning a term line and a colon line into a markdown definition list."
quickAnswer: "For a markdown definition list, start with the section What plain CommonMark does, which has the spec search and pandoc's output with definition_lists off. Reader defaults and flags are listed under The definition_lists extension. Numbered steps and a test run sit under Write a definition list with pandoc. Five small test files and what pandoc gave are covered under Blank lines, markers and spacing. An HTML dl block and what pandoc did with it are in the section A raw HTML block."
keyTakeaways:
  - "The section What plain CommonMark does has the spec search result and pandoc's output for a term and a colon line."
  - "Pandoc reader defaults sit under The definition_lists extension, along with the flags that turned it on and off in the tests."
  - "The section Write a definition list with pandoc walks through five numbered steps."
  - "The section Blank lines, markers and spacing covers five small test files and what pandoc gave."
  - "The section A raw HTML block shows what pandoc did with a dl block, including one that holds Markdown asterisks."
publishedDate: 2026-10-20
dateModified: 2026-10-20
author: Bobby Huang
cluster: B
role: post
status: published
faq:
  - q: Is there definition list syntax in CommonMark?
    a: "Under What plain CommonMark does, you will find the spec search result and what pandoc's commonmark reader made of a term and a colon line."
  - q: How do I turn on definition lists in pandoc?
    a: "Turning the extension on and off is covered under The definition_lists extension, with the reader flags from the tests."
  - q: Can I put Markdown inside an HTML dl block?
    a: "Test output for that case is in the section A raw HTML block."
related:
  - raw-html-in-markdown
  - markdown-code-blocks
  - markdown-tables
---

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`:

```markdown
Jane Doe
:   Owner of Doe Holdings.
```

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

```html
<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:

```html
<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:

```markdown
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:

```markdown
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:

```markdown
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](markdown-code-blocks.md).

### 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](raw-html-in-markdown.md); this section sticks to the test.

The file `dl-html.md` holds four lines:

```html
<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:

```html
<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](markdown-tables.md) 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](/features), the [help pages](/help) and the [roadmap](/roadmap) for where each part stands.

Check [sashmark.com](https://www.sashmark.com/) for updates.