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
@geoff I don’t think I’ve ever reached for that either, definitely good to know!
@geoff whoa! I didnโt think it existed in Markdown! (shall test in my blogโs flavor CommonMark for support)
@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
@anniegreens Heck yeah, let me know how it goes!
@mrtrimble You know, those would be really great to use for the property values in almanac pages. ๐ง
@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.
@andre @sarajw Ooo, checking this out. ๐
@anniegreens @geoff neat! but yep not part of Markdown spec it requires an extension. Thereโs one for markdown-it too https://github.com/markdown-it/markdown-it-deflist
GitHub – markdown-it/markdown-it-deflist: Definition list (<dl>) tag plugin for markdown-it markdown parser
@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.
Likes
Reposts