Ask HN: Do you miss description lists (<dl>) in Markdown (GFM)? | Hacker News Reader

Ask HN: Do you miss description lists (<dl>) in Markdown (GFM)?

9 pointsnetworked9 comments

"Item - description or nothing" lists are everywhere in software documentation and discussion. Usage messages are one example. "Awesome lists" on GitHub are another, but they are written as unordered lists. I wonder if they would be if GitHub Flavored Markdown or CommonMark supported description lists (other than through raw HTML). Do you ever miss them?

Some implementations of Markdown support description lists, like Pandoc's. There is basically an established syntax, although it differs slightly between implementations and is not the simplest to parse: https://talk.commonmark.org/t/description-list/289/.

View on HN

Yes and no. Description lists are just a semantic distinction and Markdown’s goal is to be readable in its raw form. This is a description list in Markdown:

- word: definition

- *word*: definition

It’s perfectly readable and conveys the intent of a description list. I wish Markdown parsers would generate a <dl> for styling purpose but it’s not a blocking point

> Description lists are just a semantic distinction

So are *bold* and _emphasis_, but that doesn't mean they don't carry value. Aside from that, a definition/description list is more like:

    - term
      1. first definition
      1. second definition
    - first term
    - second term
      1. definition

vs. the KramDown implementation that GitHub once used for a description list:

    term
    : first definition
    : second definition
    first term
    second term
    : definition

And KramDown's output was specific to the definition list case (and still calls them "definition lists" and not "description lists") by bolding the terms and indenting but not bulleting the definitions. Multiple terms are associated with the same item in a definition list, but separate items in an unordered list.

Since this is in the context of GFM, which exists primarily to render Markdown on GitHub, the output behavior is arguably more significant than the input readability.

I never knew about <dl> until I saw this post. So I never missed them.

What is the advantage of <dl> over bullet-lists?

It provides more structure. You can think of a description list as a two-column table, except easier to nest and more mobile-friendly than an actual HTML table.

My website introduces a lot of terms in a different language.

Instead of using definition lists, I link to glossary pages.

In Markdown, I use wikilink syntax for those links, so [[Anmeldung]] translates to a link to that glossary page.

Then I use a bit of JavaScript to make the link open a tooltip instead of a separate page.

I find this approach easier for me and for the readers. You can see it in action here: https://allaboutberlin.com/guides/anmeldung-in-english-berli...

  * Coffee__  
    Superior hot beverage.
  * Tea__  
    The other one.

__ (two spaces to force new line)

I missed them renaming <dl> from definition list in HTML5. Use them all the time in MediaWiki markdown.

Not really, if I feel the need to add some description in a list I would likely make a table instead.

I really like the orgmode syntax for this:

- term :: description

I use it all the time as a glossary for my notes.

Reply on news.ycombinator.com