Markdown definition lists: terms, definitions, and compatibility

To write a definition list in Markdown, put the term on its own line, then write each definition on the next line starting with a colon and a space (: definition). This pairs a term with one or more definitions, producing an HTML <dl>. Definition lists are an extended feature, not part of core Markdown, CommonMark, or GitHub Flavored Markdown, so support depends on the flavor: Pandoc, MultiMarkdown, and Markdown Extra handle the syntax, while other tools need raw HTML.

Markdown definition lists syntax reference

The term sits on a line by itself. Each definition begins with a colon and a space. A blank line separates the term from the definitions in most parsers.

Markdown definition lists key facts

• Write the term on its own line, then start each definition with a colon and a space, for example : definition.
• The term becomes an HTML <dt>, each definition becomes a <dd>, and both sit inside a <dl>.
• One term can have several definitions, and several terms can share one definition.
• Definition lists are not in CommonMark, GitHub Flavored Markdown, or John Gruber's original Markdown.
• The Term then : definition syntax originated in PHP Markdown Extra and was adopted by MultiMarkdown and Pandoc.
• For a portable definition list, write raw HTML with <dl>, <dt>, and <dd> on renderers that allow inline HTML.

Check compatibility before using definition lists

Definition-list syntax is not part of CommonMark or GitHub Flavored Markdown. It is available in systems such as Pandoc, MultiMarkdown, and Markdown Extra, but the exact spacing and generated HTML can differ.

Use definition lists when the destination renderer explicitly supports them and the term-to-description relationship matters. For a README that must render on GitHub, use bold terms followed by ordinary paragraphs, a two-column table, or a standard list instead. Test the file in its publishing destination before relying on this syntax for a glossary or API reference.

Basic syntax

To create a definition list, write the term on one line and the definition on the next, starting with :.

Markdown

Apple
: A round fruit with red or green skin.

Rendered output

HTML output

<dl>
  <dt>Apple</dt>
  <dd>A round fruit with red or green skin.</dd>
</dl>

The term maps to a <dt> (definition term) and each definition maps to a <dd> (definition description), both wrapped in a <dl> (definition list).

Multiple definitions per term

A single term can have more than one definition. Add another line starting with : for each one.

Markdown

Term
: The first definition.
: The second definition.

Rendered output

HTML output

<dl>
  <dt>Term</dt>
  <dd>The first definition.</dd>
  <dd>The second definition.</dd>
</dl>

Both definitions appear under the same term, each in its own <dd> element.

Multiple terms sharing definitions

Several terms can share one or more definitions. Put each term on its own line, then follow with the definitions.

Markdown

First term
Second term
: A definition that applies to both terms.

Rendered output

HTML output

<dl>
  <dt>First term</dt>
  <dt>Second term</dt>
  <dd>A definition that applies to both terms.</dd>
</dl>

Each term becomes its own <dt>, and the shared definition follows as a <dd>.

Multiple entries in one list

You can list several terms with their definitions in a row. Separate each term-and-definition group with a blank line to keep the source readable. Most parsers keep them all inside one <dl>.

Markdown

Apple
: A pomaceous fruit.

Orange
: A citrus fruit.

Rendered output

HTML output

<dl>
  <dt>Apple</dt>
  <dd>A pomaceous fruit.</dd>
  <dt>Orange</dt>
  <dd>A citrus fruit.</dd>
</dl>

Definitions with block content

In Pandoc and MultiMarkdown, a definition can hold more than one paragraph or other block content such as lists. Indent the continuation lines so they line up under the definition.

Markdown

Term
: The first paragraph of the definition.

    A second paragraph, indented to stay inside the definition.

Rendered output

A second paragraph, indented to stay inside the definition.

Loose and tight lists

Some processors distinguish loose definition lists, where a blank line sits between the term and the definition, from tight ones, where they are adjacent. A loose list often produces definitions wrapped in <p> tags, while a tight list may not.

Markdown (loose)

Term

: A definition preceded by a blank line.

Rendered output

Flavor differences

Definition lists are an extended feature. They are absent from CommonMark, from GitHub Flavored Markdown, and from John Gruber's original Markdown. The Term then : definition syntax originated in PHP Markdown Extra and was adopted by MultiMarkdown and Pandoc.

Other platforms (Obsidian, Notion, Reddit, Slack)

• Obsidian: does not support definition list syntax by default. It can be added through a community plugin.
• Notion: does not support definition list syntax. The colon lines render as plain text.
• Reddit and Slack: do not support definition lists. The syntax renders as literal text.

Because definition lists are not in CommonMark or GFM, the most portable way to get a real definition list is to write raw HTML with <dl>, <dt>, and <dd>, on renderers that allow inline HTML.

For the full comparison of how flavors differ across all elements, see Markdown flavors.

How Markdific renders it

Markdific renders definition lists written with the standard Term then : definition syntax as paired term and definition blocks. Each term appears above its associated definitions.

Because definition lists are flavor-specific, a document that uses them may render as plain text in tools that do not support the syntax.

Try it in the Markdific online editor.

Common mistakes and gotchas

• Assuming definition lists are universal. They are not in CommonMark, GFM, or classic Markdown. On those, the colon lines render as ordinary paragraphs.
• Missing the space after the colon. Write : definition, not :definition. Most parsers expect the space.
• Indenting the term. The term should start at the left margin. Leading spaces can turn it into a code block or break the list.
• Wrong blank-line placement. The blank line rule between the term and the definition affects whether definitions are wrapped in paragraphs. Test if the spacing matters to you.
• Expecting it to work on GitHub. GitHub does not render this syntax. Use raw HTML with <dl> if you need a definition list there.
• Forgetting to indent block content. Multi-paragraph definitions need their continuation lines indented so they stay inside the definition.

Best practices

• Confirm your target renderer supports definition lists before using the syntax, since CommonMark and GFM do not.
• Keep the term on its own line at the left margin and start each definition with a colon and a space.
• Add a blank line between separate term-and-definition entries to keep the source readable.
• For portable documents, use raw HTML <dl>, <dt>, and <dd> instead, on renderers that allow inline HTML.
• Reserve definition lists for genuine term-and-definition content such as glossaries, not as a general layout tool.

HTML equivalent

Markdown definition lists compile to the HTML <dl> element, with each term in a <dt> and each definition in a <dd>.

Markdown

Term one
: Definition of term one.

Term two
: Definition of term two.
: A second definition of term two.

HTML output

<dl>
  <dt>Term one</dt>
  <dd>Definition of term one.</dd>
  <dt>Term two</dt>
  <dd>Definition of term two.</dd>
  <dd>A second definition of term two.</dd>
</dl>

FAQ

How do you write a definition list in Markdown? Write the term on its own line, then write each definition on the next line starting with a colon and a space (: definition). The term becomes a <dt> and each definition becomes a <dd>.

Do definition lists work on GitHub? No. GitHub Flavored Markdown does not support definition list syntax. If you need a definition list on GitHub, write raw HTML with <dl>, <dt>, and <dd> instead.

Does CommonMark support definition lists? No. Definition lists are not part of the CommonMark specification. In a plain CommonMark renderer, the colon lines render as ordinary paragraphs.

Which flavors support definition lists? Markdown Extra, MultiMarkdown, and Pandoc support the term-and-colon syntax. The feature originated in PHP Markdown Extra and was adopted by the others.

Can one term have multiple definitions? Yes. Add another line starting with a colon and a space for each definition. Each one becomes its own <dd> under the same term.

Can multiple terms share a definition? Yes. Put each term on its own line, then follow with the definitions. Each term becomes a separate <dt>, and the definitions apply to all of them.

What HTML does a Markdown definition list produce? A <dl> element containing a <dt> for each term and a <dd> for each definition.

Can a definition contain multiple paragraphs or block content? Yes, in Pandoc and MultiMarkdown. Indent the continuation lines so they line up under the definition, and a definition can then hold more than one paragraph or other block content such as a nested list. The exact indentation and blank-line rules vary by processor, so test in your target tool.

Why does my definition list render as plain text? The renderer does not support the syntax. CommonMark, GitHub Flavored Markdown, and classic Markdown show the colon lines as ordinary paragraphs. Use Pandoc, MultiMarkdown, or Markdown Extra, or write raw HTML with <dl>, <dt>, and <dd>.

What is the difference between a definition list and a bullet list in Markdown? A bullet list groups items of equal weight, each marked with a dash or asterisk and mapped to <li> inside a <ul>. A definition list pairs a term with its explanation, mapping to <dt> and <dd> inside a <dl>, which is the right structure for glossaries and term-and-definition content.

How do you write a glossary in Markdown? List each term on its own line with its definition on the following line starting with a colon and a space, and separate entries with a blank line. In a flavor that supports definition lists this produces one <dl> with a <dt> and <dd> per entry. For portability, use raw HTML <dl> instead.

Sources and compatibility references

• Pandoc User's Guide
• CommonMark 0.31.2

Use these primary references for syntax rules. Renderer behaviour can still vary by version and configuration, so preview important documents in their final destination.

Related pages

• Markdown documentation hub
• Lists in Markdown
• Footnotes
• Inline HTML in Markdown
• Heading IDs
• Markdown flavors compared