On September 18, 2024, I learned...

Definitions Lists in Markdown

I’ve re-discovered the definition list (<dl>) element and a newfound love for it. I’d never reached for one when writing in Markdown before (regular-ol’ lists are so darn easy) but found myself needing to this morning.

It’s not tough to find the information. This is just the first time I’ve looked it up and now I see that definition lists are just as easy and convenient in Markdown as ordered and unordered lists.

First Term
: This is the definition of the first term.

Second Term
: This is one definition of the second term.
: This is another definition of the second term.

That’s it. Ordered list items are prepended by a hash symbol (#), unordered list items are prepended by an asterisk (*) or dash (-), and now I know that definition list items (well, technically it’s the definitions, not the terms) are prepended by a single colon (:).

Thank you, Matt Cone!

32 Comments

  1. # September 18, 2024

    @geoff I don’t think I’ve ever reached for that either, definitely good to know!

    Reply
  2. # September 18, 2024

    @geoff whoa! I didnโ€™t think it existed in Markdown! (shall test in my blogโ€™s flavor CommonMark for support)

    Reply
  3. # September 18, 2024

    @geoff oh nice! And will the markdown translator thing stick the <dl></dl> in before and after? I guess it already does that with ul and ol so why wouldn’t it… Sweet

    Reply
  4. # September 18, 2024

    @anniegreens Heck yeah, let me know how it goes!

    Reply
  5. # September 18, 2024

    @mrtrimble You know, those would be really great to use for the property values in almanac pages. ๐Ÿง

    Reply
  6. # September 18, 2024

    @sarajw It does! Youโ€™d think it wouldnโ€™t when the term isnโ€™t formatted, but perhaps the single break before the term description is what triggers that.

    Reply
  7. # September 18, 2024

    @andre @sarajw Ooo, checking this out. ๐Ÿ‘€

    Reply
  8. # September 18, 2024

    @geoff I use them all the time for API docs. I generally try to follow MDN’s document structure which makes things nice and readable.

    Unfortunately, the shorthand syntax is an optional extension not included in GitHub Flavored Markdown as far as I can tell, so I still need to stick with raw markup in my repos.

    Reply

Leave a Reply

Markdown supported