Markdown Definition List

When writing technical docs or building a glossary, you often need paired "term — explanation" structures. HTML has dedicated <dl>, <dt>, <dd> tags for this, but in Markdown, definition lists are an extended feature — meaning not every platform supports them. Let's walk through the syntax, compatibility, and fallback options so you know exactly what works where.

What Is a Definition List

A definition list is a set of "term + explanation" pairs, like this:

Markdown
  A lightweight markup language for writing formatted documents in plain text

HTML
  HyperText Markup Language, the standard language for web pages

In HTML, this maps to <dl> (definition list), <dt> (definition term), and <dd> (definition description). Markdown's definition list syntax is essentially a shortcut for these three tags .

Definition List Syntax

Colon Notation (Most Common)

Most Markdown parsers that support definition lists use the colon syntax. The pattern is simple: the term goes on its own line, and the definition starts on the next line with a colon and a space:

Markdown
: A lightweight markup language for writing formatted documents in plain text

HTML
: HyperText Markup Language, the standard language for web pages

When rendered, "Markdown" and "HTML" appear as terms (<dt>), and their explanations are indented as definitions (<dd>) .

Multiple Definitions for One Term

A single term can have multiple definitions, each on its own colon-prefixed line:

API
: Application Programming Interface
: Also commonly refers to the callable interface a service exposes to the outside

This comes in handy when writing technical docs — some terms genuinely need explaining from different angles .

Multi-line Definitions

When a definition is long enough to span multiple lines, continuation lines should be indented (typically 2–4 spaces):

Python
: An interpreted high-level programming language
  Created by Guido van Rossum and released in 1991
  Known for its clean, readable syntax

The second and third lines are indented by 2 spaces. They get merged into the same <dd> tag and rendered as a single paragraph .

Formatting Inside Definitions

Definitions can contain regular Markdown formatting — bold text, links, inline code, and more:

Variable
: A named container in a program for **storing data**, e.g. `user_name = "Alice"`

JSON
: JavaScript Object Notation, a lightweight [data interchange format](https://www.json.org/)

This makes definition lists far more expressive than plain text .

HTML Fallback: Works Everywhere

Honestly, the biggest pain point with definition lists isn't the syntax itself — it's that many platforms simply don't support it. When that happens, writing raw HTML with <dl>, <dt>, and <dd> is the most reliable fallback:

<dl>
  <dt>Markdown</dt>
  <dd>A lightweight markup language for writing formatted documents in plain text</dd>
  <dt>HTML</dt>
  <dd>HyperText Markup Language, the standard language for web pages</dd>
</dl>

The advantage here is that nearly every Markdown renderer preserves raw HTML tags as-is. It's more verbose, but at least your content renders correctly .

I once used the colon syntax for API parameter docs in a GitHub README, pushed it up, and found everything was garbled — the colon-prefixed lines were treated as plain text. Turns out GitHub's Markdown renderer doesn't support this extension at all, so I had to go back and rewrite everything with HTML tags. Lesson learned: if you're not sure whether the target platform supports it, HTML is the safe bet.

Platform Compatibility Table

This is probably what you came here for. Here's how major platforms handle definition lists:

Key takeaways:

• GitHub and Obsidian are the most common platforms that don't support it — you'll need HTML tags on both
• GitLab is one of the few major platforms with native colon syntax support, so you can use it directly
• Python-Markdown requires manual extension enabling. The config looks like md = markdown.Markdown(extensions=['def_list'])

When I was using Python-Markdown for a static site generator, it took me a while to figure out why definition lists weren't rendering — I'd forgotten to add def_list to the extensions list. The tricky part is that Python-Markdown doesn't throw an error; it just silently treats the colon-prefixed lines as plain text.

Practical Use Cases

Definition lists shine in these scenarios:

Glossaries / Vocabularies — This is the classic use case. Put a glossary at the top of your technical doc so readers can quickly look up unfamiliar terms:

Glossary
: API: Application Programming Interface
: SDK: Software Development Kit
: IDE: Integrated Development Environment

API Parameter Docs — Backend API docs frequently use definition lists for parameter descriptions:

username
: The user's name, 3–20 characters, letters and digits only

password
: The user's password, 8–32 characters, must include uppercase, lowercase, and digits

Configuration Option Descriptions — Explaining available settings in a project config file:

port
: The port the server listens on, defaults to `8080`

debug
: Whether to enable debug mode, accepts `true` or `false`

If you don't need paired "term — explanation" structures and just want to list items, a regular Markdown list does the job just fine — no need to force it into a definition list format.

FAQ

How do I write a definition list on GitHub?

GitHub doesn't support the colon syntax. You have two options:

One, write raw HTML tags:

<dl>
  <dt>Term</dt>
  <dd>Definition</dd>
</dl>

Two, use a table to simulate the look. It won't have <dl> semantics, but visually achieves the "term — explanation" effect:

| Term | Definition |
|------|-----------|
| API  | Application Programming Interface |

Is the definition list part of the Markdown standard?

No. Definition lists are an extended syntax — they're not in the CommonMark spec and weren't in John Gruber's original Markdown either . The feature was first introduced by PHP Markdown Extra and later adopted as an extension by MultiMarkdown, Python-Markdown, and others.

Can I use definition lists in Obsidian?

Obsidian doesn't currently support the colon syntax for definition lists. However, you can write raw HTML <dl> tags directly in Obsidian — they render and export without issues.

Can definition lists be nested?

In theory, yes. Some parsers that support definition lists allow you to nest additional lists or code blocks inside a <dd>. But nesting behavior varies across parsers, so test on your target platform first. When in doubt, keeping things flat is the safest approach.

References

: Markdown Guide — Extended Syntax: Definition Lists: Python-Markdown Official Docs — Definition Lists Extension: Fuchsia Project Docs — Markdown Reference Guide: MarkdownLang — Definition Lists: GitLab Docs — GitLab Flavored Markdown (GLFM)