Markdown Definition Lists: Glossary Syntax Guide

Term Name
: Definition of the specified term.
: Second definition.

Definition lists (formally known as description lists in HTML5) are specialized structures designed to pair terms with their corresponding definitions, descriptions, or values.

Unlike bullet lists or numbered sequences, definition lists establish a clear semantic relationship between a concept and its explanation. They are widely used for technical glossaries, API dictionaries, FAQ sections, and metadata property sheets.

Extended Markdown definition list syntax

In Extended Markdown (PHP Markdown Extra, Pandoc, Kramdown), a definition list consists of a term on the first line, followed by one or more definition lines starting with a colon (:):

Apple Silicon
: A series of system on a chip (SoC) and system in package (SiP) processors designed by Apple Inc. utilizing the ARM architecture.

ScreenCaptureKit
: A native macOS API framework introduced in macOS 12.3 providing high-performance, low-overhead screen and system audio recording.

Local-First Software
: An architectural paradigm where data is stored primarily on the client device in open formats, ensuring complete user autonomy and offline utility.

This compiles to semantic HTML:

<dl>
  <dt>Apple Silicon</dt>
  <dd>A series of system on a chip (SoC)...</dd>
  <dt>ScreenCaptureKit</dt>
  <dd>A native macOS API framework...</dd>
</dl>

Multiple definitions for a single term

A single term can possess multiple definitions or explanatory clauses. Prefix each subsequent definition with a colon:

SQLite FTS5
: An SQLite virtual table module that allows users to perform full-text searches on a set of documents.
: The underlying search engine utilized by Oyma to deliver sub-50ms offline search across thousands of vault notes.

Multi-paragraph definitions

Definitions can span multiple paragraphs or contain code blocks by indenting subsequent lines by four spaces:

Whisper
: An automatic speech recognition (ASR) system trained on hundreds of thousands of hours of multilingual audio data.

    In Oyma, quantized Whisper models run locally on the Apple Neural Engine,
    ensuring zero audio data leaves your Mac.

Fallback syntax for standard CommonMark

Because definition lists are an extension rather than part of core CommonMark, writers targeting strict CommonMark environments (such as GitHub READMEs) often use one of two standardized fallbacks:

Fallback 1: Bold bullet list (Most common)

- **ScreenCaptureKit:** Native macOS framework for system audio capture without external bots.
- **SQLite FTS5:** Full-text search engine powering instant keyword queries across vault notes.
- **CommonMark:** Rigorous plain-text specification for unambiguous document formatting.

Fallback 2: Direct semantic HTML

Because all Markdown parsers pass raw HTML through to the output, you can write native <dl> tags directly:

<dl>
  <dt>Local-first</dt>
  <dd>Software that stores data on your computer first, cloud second.</dd>
</dl>

Working with terms and definitions in Oyma

In Oyma:

• Both extended definition lists and bold glossary bullet lists render with refined native macOS typography.
• You can cross-reference terms using bidirectional [[WikiLinks]] ([[ScreenCaptureKit]]), connecting terms directly to dedicated glossary or reference pages.
• Fast full-text search indexes both terms and definitions with sub-50ms latency.

Frequently asked questions

What is the syntax for a definition list in Markdown?

Place the term on its own line, followed on the next line by a colon (`:`), a space, and the definition text (`Term : Definition`). Multiple definitions can be chained with additional colon-prefixed lines.

Does standard CommonMark support definition lists?

CommonMark 0.31 does not specify definition lists; they originated in PHP Markdown Extra and are supported in Pandoc, MultiMarkdown, Kramdown, and various documentation generators.

What HTML elements do Markdown definition lists compile to?

A Markdown definition list compiles directly to semantic HTML definition elements: `

` (description list), `

` (definition term), and `

` (definition description).

What is the best alternative if my Markdown parser does not support definition lists?

If your target parser lacks native definition list support, use bold terms followed by indented descriptions (`- **Term:** Definition text`) or raw semantic HTML `

Term

Definition

` tags.