Description List

Extensions
1

Not commonly found in most implementations afaik, though I quite like the semantics and it provides an opportunity for yet-another list format…

Any imps that do use <dd>, <dl> etc?

Or any particular reason they’ve been avoided?

11 Likes
2

Description lists are already implemented by many processors. It would be nice to see them featured in standard markdown.

Python-Markdown, Kramdown, Maruku, php-markdown/extra and pandoc all use the following syntax

topic
: description 1
: description 2

Kramdown allows multiple topics

topic 1
topic 2
: description

  > with nested markup

Pandoc raises an interesting point about lazy wrappings:

To see why laziness is incompatible with relaxing the requirement of a blank line between items, consider the following example:

bar
: definition
foo
: definition

Is this a single list item with two definitions of “bar,” the first of which is lazily wrapped, or two list items? To remove the ambiguity we must either disallow lazy wrapping or require a blank line between list items.

The nice thing about this syntax for definition lists is that processors that do not understand it natively will produce a single paragraph with a colon in the middle:

<p>topic : description</p>
6 Likes
3

Just wanted to point out that parsing multiple topics is not easy without backtracking. Consider this example:

term1
term2
...
term999
:   definition

In the above case a parser needs to consume 999 lines to detect a definition list. While in this case:

term1
term2
...
term999

next paragraph

the parser consumed 999 lines and detected that there is no definition list and it needs to backtrack and reparse the whole block element as something else (possibly a plain text paragraph).

AFAIK Pandoc also requires that a definition line is indented four spaces. Such as:

term1
:···definition

because otherwise it is all too easy to make an unintended definition list.

1 Like
4

There seems to be a wide agreement on how description lists should be represented.

What is the next towards the recognizion of this established syntax in CommonMarkdown?

1 Like
5

How would a list of singular description list be detected? Can it be done like this?

cat: bert
dog: howard
bird: fred
snake: slither
6

The definition line must start with a colon. For reference, here is the definition list documentation for Markdown Extra. This syntax is also used in Pandoc, Kramdown, and other implementations. Having the colon on the same line would cause issues as many sentences use literal colons.

7

Okay I’ll move the proposal for key:value recognition to Autodetect key:value as visible metadata

Btw

I found myself often typing single line description like this (when I want to remind myself that “this sentence defines the latter”):

Dog :~ An animal with two legs

Personally I think this apply to this as maybe we can do a description list like

Animals
:~ Cat rocks
:~ Dog bark
:~ Bird race
Dog :~ An animal with two legs
Cat :~ Master specie
Empty :~
Not Empty :~ it has something

Benefit of :~ over : is that it is very distinctive, and carries an explicit visual directionality.

Hmmm… i wonder if there is a way to reference or link to the description. Imagine being able to hyperlink to a definition. It will be very useful for formula list etc… or symbol definition

8

In this discussion we should be clear about the goal: to provide a syntax for describing HTML definition lists in Markdown. The Markdown Extra syntax does that well; indeed if you look the way browsers render definition lists by default they line up with Markdown syntax surprisingly well:

Dog
An animal with two legs

Notice how the definition description is indented like in the Markdown Extra syntax?

Dog
: An animal with two legs

In writing it’s also common to see data terms and descriptions on the same line, separated by a colon. This is makes borrowing the colon as a marker appropriate for the Markdown syntax. Whether definition lists should be described on a single line in Markdown questionable though (even if CSS is used to render it that way). Although some writers expect to write definition lists this way, there might be a selection bias. If you asked another group of writers they might prefer putting the description indented on the next line. It’s the line break issue all over again.

The use of the ~ character does not look like either approach to formatting definition lists though, so it’s hard to see a clear reason to change from the well established Markdown Extra syntax.

The idea of creating a hyperlink to the definition is interesting. If the description is close to the term, what is the advantage? If it is not close by, perhaps using footnotes is the way to go? Or figures. In either case it is beyond the scope of the standard description list syntax.

9

I think my biggest issue with the current

Dog
: An animal with two legs

is that it is too bloated for single definitions. If I am doing quick list of words and definitions, I want each term to take only a single line. Preferrably I wanted

dog : 4 legged friend
cat : feline daemon
bird : hungry flying fellow

However there is some issues with : being used in other context other than definition list. Thus I opted for :~ instead for key:value descriptions.

dog  :~ 4 legged friend
cat  :~ feline daemon
bird :~ hungry flying fellow

Perhaps a compromise could be made, in that we support both forms below. Thus allowing the first form that takes more lines but is more flexible, but at the same time support a more compact notation.

Dog
: An animal with two legs

dog  :~ 4 legged friend
cat  :~ feline daemon
bird :~ hungry flying fellow

(I think the context for me. Is that I tend to have a “symbol” list or a legends of mathematical symbols, thus the current form you are proposing will double my list by 2x . Thus bloating my list too much. So i guess in terms of audience, the people this matter most to is not typical writers, but to academics.)

Tooltip definition hyperlink

In terms of hyperlink. I would preferred if the behaviour was more of a tooltip. E.g. you hover over, and get the summary definition, but when you click, you jump to the full definition. How is it implemented. (e.g. hovering over word hydrogen gets a brief description of what hydrogen is, but clicking it jumps you to definition list) Well I haven’t thought that far ahead.

10

Spreading out text is in line with the philosophy of Markdown, for example using line breaks instead of wrapping text is encouraged. I can see a potential issue on small screens, for example if you’re comparing lots of key/value pairs on a mobile phone screen. I don’t think :~ is the right marker to use here, maybe -> instead:

Dog -> An animal with two legs

I’m not entirely convinced of the need though. Presumably you would want to reuse the marker for multiple definition lists. That creates an inconsistency if : is used as a marker (as well) as it cannot be used on the same line, potentially causing confusion for writers. It might be better to stick with a single marker, but if a marker other than : is chosen we’re going to break a lot of existing implementations. I think the Markdown Extra syntax is quite widely used (I’ll look into compiling a list), so changing the syntax may an uphill battle.

This sounds like a job for CSS/JavaScript. HTML (and thus Markdown)'s role is describing the content, rather than specific presentation or behaviour. Maybe some post processing would be needed to add anchor tags to the rendered HTML, but there shouldn’t be a need to change the Markdown syntax if there is a general pattern.

11

Well my first preference is : of course like

dog: 4 legged friend
cat: feline daemon
bird: hungry flying fellow
animals
: description 1
: description 2
lizard: happy fellow

but -> is fine for me as well. Basically I don’t mind any options, as long as there is also a ‘compact’ option for single key:value description list entry,

1 Like
12

Flavours using the Markdown Extra syntax for definition lists:

Flavours that do not support definition lists:

Let me know if I’ve missed any and I’ll update the list.

2 Likes
13

I think this a very important feature! Probably the one I’m missing the most. I’d really like to see it included!

1 Like
14

Yes, I agree that this is an important one.

There is a fairly standard format for these, originally due to PHP Markdown Extra and adopted by pandoc.

https://michelf.ca/projects/php-markdown/extra/#def-list

I’m not sure this is optimal, but I could live with it.

1 Like
15

In Latex would you write

\begin{description}
\item[txt] text files
\item[bin] binary files
\end{description}

and render it a bit different than what have been proposed here. See page 5 in this pdf.

I am often missing this feature when writing documentations.

16

Sorry to bump an old thread, but has there been any progress on this?

Many of my markdown documents are written as:

topic1
: - info 1
  - info 2
  - info 3

topic2
: - info 1
  - ...

which renders much nicer than the

#### topic 1
- info 1
- info 2
 ...

alternative.

17

I don’t believe so, since completing the core spec is the current focus.

Why not…

topic1
: info 1
: info 2
: info 3

topic2
: info 1
: ...

…which would be compatible with existing implementations?

18

Is the following really compatible with the existing CommonMark implementation?

topic1
t: info 1
t: info 2
t: info 3

If I copy-paste it into the CommonMark tutorial I get topic1 : info 1 : info 2 : info 3 as output.

19

I meant that the syntax is compatible with these Markdown implementations (which are not CommonMark compliant, but are widely used).

20

Crossposting an idea I had from my inline lists thread:

The <DL> are calle “description lists” in HTML5 instead of “definition lists”. The scope of them also changes a little. I don’t see them as only suitable for glossary or an alphabetically sorted technical terms list anymore.

That means that I see the “term” as being more like a list symbol, just like “1.”, “a)”, “i.” or bullets and dashes.

I would suggest the following as an alternative for the description list syntax:

~ term1 : definition 1
~ term2
: definition 2

As an example i would like to show you a medical menemonic for coma reasons. The initial letters of the word “smashed” hint to the conditions that can be the reason for the coma. But obviously this list is not a “definition list” in the sense that the “term” (letters) are “defined” by the “definition”.

~ S : stroke
~ M : meningitis
~ A : alcohol
~ S : seizures
~ H : hypoglycaemia
~ E : epilepsy
~ D : drugs

The tilde is indeed similar to the dash in visually representing a
new list item, but there would be no ambiguity about whether you want an
unordered list item or a description list item.

The tilde would also remove the need for a look-back when parsing an detecting a defintion list.

The combination would probably make the whole thing quite distinct. The possibility of an unintended definition lists is nearly wiped out that way.

When using the tilde the ambiguity of lazy wrapping is eliminated.

Both the tilde and the colon could still be easily used for other
purposes, because they would only be a description list in combination.
To get a empty description use ~ term : to get an empty term use ~ : description.