Description List

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


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

:~ 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

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:

An animal with two legs

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

: 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.

I think my biggest issue with the current

: 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.

: 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.

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.

Well my first preference is : of course like

dog: 4 legged friend
cat: feline daemon
bird: hungry flying fellow
: 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

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.


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

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.

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

1 Like

In Latex would you write

\item[txt] text files
\item[bin] binary files

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.

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

Many of my markdown documents are written as:

: - info 1
  - info 2
  - info 3

: - info 1
  - ...

which renders much nicer than the

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


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

Why not…

: info 1
: info 2
: info 3

: info 1
: ...

…which would be compatible with existing implementations?

Is the following really compatible with the existing CommonMark implementation?

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.

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

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.

I like this better than the PHP Markdown Extra syntax. Not only does it solve the look-ahead problem, but I always found placing the colon at the beginning of a line awkward (a notation that only Forth programmers can love … :wink: ).

Note that “definition lists” (I just can’t cope with the HTML5 renaming frenzy …) are not specific to HTML; similar elements exist

  • in DocBook as <variablelist>, or

  • in the NISO Journal Article Tag Set (JATS) as <def-list> (properly named “definition list” …),

  • also in the ISO Standards Tag Set (ISOSTS) as <def-list> too (since ISOSTS is an adaptation of NISO JATS), and

  • in ISO 12083:1994 there are similar <deflist>, <term>, <dd> elements (again described as a “definition list” …) with this content model:

    <!ELEMENT deflist - - ((head, ddhd)?, term, dd)>
  • and ISO/IEC TR 9573:1988, ISO/IEC TR 9573-11:1991 (<DL>, <DT>, <DD>), and ISO/IEC 9573-11:2004 (<tl>, <termdef>, <termdes>) are more examples.

So there is amply justification for having a dedicated and nice Markdown syntax for this kind of lists in my opinion.

Please note, that my suggestion is to allow either single-line term-definition-pairs or multiple terms and/or multiple definitions in new lines:

~ term 1
~ term 2
: definition of term 1 and 2
: another definition of term 1 and term 2
~ term 3 : single definition of term 3

The following might cause problems, so i’m not sure how to exactly treat them. I guess having more than one many-to-many pair in a line (as in term 8 & term 9) doesn’t contain much logic.

~ term 4 : definition of term 4
: another definition of term 4
~ term 5 ~ term 6 : definition of term 5 and 6
~ term 7 : definition of term 7 : another definition of term 7
~ term 8 : def 8 ~ term 9 : def 9
~ term 10 : definition 10
lazy continuation of definition 10
~ term 11 : definition 11
....another paragraph of definition 11 (dots are spaces)
~ term 12
: definition 12
....another paragraph of definition 12 (dots are spaces)

What about empty terms and definitions? Skip them?

~ term 1 : {empty definition 1 on same line}
: definition 2
: {empt defintion on new line}

What about a definiton list starting with a definition? I suggest the following:

: not a definition, maybe needed for another syntax.

~ : definition for "empty term"

Have i missed anything :wink:

Please, after 2 years of discussion any of the widely discussed here is valid, just implement it please … normal people just want to have description list

When you search for an extension, official docs sends you here … what i must search here to get a working description list ?? I just found how people love to talk and talk around about a simple thing

You’re not sure? Implement 2 or 3 types and let the people use it and test it … but 2 years with no code and too much talking is all contraproducent, because as me there would be a lot of people just throwing the requirement and switching to a different one.

I want to follow specs, but this is a WAY slow spec dev … think about something more sofisticated than a simple description list … 10 years?



You can use markdown-it, which follows the CommonMark spec, along with it’s definition list plugin which uses the Markdown Extra syntax.

I don’t know whether you collect Spec suggestions for extensions yet, but i would suggest the following:

For simplicity i would suggest the following.

  • Define the description list items just like the other list items.
  • put a “special case” after the “basic case” that allows multiple items on the same line.
  • (Restricting the sequence of items to multiple “names” ~ name 1 ~ name 2 ~ name 3 ~ name 4 followed by only “values” : value 1 : value 2 : value 3 : value 4 would create more problems than it would solve: Would ~ name 1 : value 1 ~ name 2 : value 2 lead to value 1 literally containing the string value 1 ~ name 2?!)
  • Restrict the definition list to only begin with “names” → there might be another syntax that needs the colon as a marker. (There are already candidates.)

5.2 List items

A list marker is a [bullet list marker] or an [ordered list marker] or a [description list marker].

A [description list marker] is a ~ or : character. The ~ is the [description name marker] and the : is the [description value marker].

  1. Basic case: …
  2. *Special case for [description list items] on the same line:
    • A description list item may consist of multiple [description list items] that are on the same line.
    • Each description [description list item] is introduced with a [description list marker] surrounded by at least one space character.
    • *anything that follows modifies the last description list item. E.g. a paragraph that follows is appended to the last item.

5.3 Lists

Two list markers are of the same type if (a) they are bullet list markers using the same character (-, +, or *) or (b) they are ordered list numbers with the same delimiter (either . or )) or © they are description list markers with either character (~ or :).

A description list must begin with a [description name marker] (~). It cannot begin with a [description value marker] (:). // this frees the colon as a character for a different syntax!

I’d like to suggest an alternative syntax here which I think reads rather intuitively, although it’s probably not yet implemented anywhere.

? term, glossary entry, question
! description, definition, answer
1 Like