{
  "schemaVersion": "1.0",
  "entity": "BlogPosting",
  "title": "Definition Lists in Markdown",
  "description": "Learn the Markdown Extra-style definition list syntax for terms and descriptions, useful for glossaries and API documentation, plus which tooling supports it.",
  "author": "hinal-acharya",
  "datePublished": "2026-07-15T00:00:00.000Z",
  "dateModified": "2026-07-15T00:00:00.000Z",
  "tags": [
    "Markdown",
    "Tutorial"
  ],
  "aeoDirectAnswers": [
    {
      "question": "How Do I Write a Basic Definition List?",
      "answer": "Write the term as a plain line of text, then on the very next line, start the definition with a colon and a space. This renders as a term/definition pairing: Definition lists are not part of core CommonMark or GFM. They originate from Michel Fortin's Markdown Extra extension, so support depends entirely on your renderer or plugin (for example, remark-definition-list in the remark/rehype ecosystem)."
    },
    {
      "question": "Can a Term Have Multiple Definitions?",
      "answer": "Yes. Add another : line directly after the first to attach a second definition to the same term. Both definitions attach to the same term: ---"
    },
    {
      "question": "Can Multiple Terms Share One Definition?",
      "answer": "Yes. Stack several term lines directly above a single definition line to apply that definition to all of them. This produces two terms sharing one definition: Definition lists work especially well for glossary pages and API parameter references, where each entry has a clear term-and-explanation shape that a plain bullet list doesn't capture semantically."
    },
    {
      "question": "Does GitHub render definition lists?",
      "answer": "No. GitHub's Markdown renderer does not support the Markdown Extra definition list syntax, so it displays as plain paragraph text with a literal colon."
    },
    {
      "question": "Do I need a blank line before a definition list?",
      "answer": "Yes, generally. Like most block-level Markdown elements, a definition list needs a blank line separating it from the preceding paragraph so the parser recognizes it as a new block."
    },
    {
      "question": "Is there a simpler alternative if my renderer doesn't support this syntax?",
      "answer": "Yes. A bold term followed by a colon and its description in a regular paragraph or bullet list (- **Term**: Definition) achieves a similar visual result without requiring extension support, at the cost of losing the semantic `//` markup. ---"
    },
    {
      "question": "What to Read Next",
      "answer": "Markdown List Guide: Ordered and Unordered Lists — Compare this syntax against standard bullet and numbered lists. Tables in Markdown - Create & Format Data — See another structured-data format for term/value pairs."
    }
  ],
  "semanticFactualBody": "Glossaries, API parameter references, and term-by-term documentation all share the same shape: a term, followed by its definition. Regular bullet lists can approximate this, but they don't semantically separate the term from its description. Definition lists solve that with dedicated syntax, though unlike most topics in this series, they come from an extension rather than CommonMark or GFM itself. This guide covers the syntax and where it does and doesn't work. --- How Do I Write a Basic Definition List? Write the term as a plain line of text, then on the very next line, start the definition with a colon and a space. This renders as a term/definition pairing: Definition lists are not part of core CommonMark or GFM. They originate from Michel Fortin's Markdown Extra extension, so support depends entirely on your renderer or plugin (for example, remark-definition-list in the remark/rehype ecosystem). --- Can a Term Have Multiple Definitions? Yes. Add another : line directly after the first to attach a second definition to the same term. Both definitions attach to the same term: --- Can Multiple Terms Share One Definition? Yes. Stack several term lines directly above a single definition line to apply that definition to all of them. This produces two terms sharing one definition: Definition lists work especially well for glossary pages and API parameter references, where each entry has a clear term-and-explanation shape that a plain bullet list doesn't capture semantically. --- S"
}