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.
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.
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?
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.
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 … 
).
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
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?
Thanks
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.
~ 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?!)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].
- Basic case: …
- *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 (c) 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, answerWhile this alludes nicely to the “question-answer-dichotomy”, I find the prefix use of question and exclamation marks—typographically—rather un-intuitive and resembling programming notations. Actually more intuitive (in this sense) would, for some folks, be
¿ term, glossary entry, question
¡ description, definition, answer
(Okay, just kidding!)
But in fact the main disadvantage is that this would just render as
? term, glossary entry, question ! description, definition, answer
in any Markdown implementation out there.
A slight variant of this idea would provide at least a readable fall-back rendering, exploiting the fact that we already have two different “unordered” list item markers:
* term:
* glossary entry:
* question:
- description, definition, answer
And is not really less intuitive either in my opinion. (Using > instead of - for the <DD> element indication would produce even nicer results in the HTML default style, where <BLOCKQUOTE> is just rendered with narrower margins. Alas, this might go too far in mis-using existing syntax.)
Or you might find + / - more appealing:
+ term, glossary entry, question:
- description, definition, answer
[Edit:] In the apples-and-oranges discussion over there I came up with this syntax (using MIDDLE DOT · as a “visible SPACE” here):
term:··
glossary entry:··
question:··
····description, definition, answer
I think this looks best (in the typescript, without the distracting “·” characters), and still renders reasonably in unaware Markdown implementations. But it’s probably not for you if you hate the end-of-line SPACE rule of Markdown!
How about colon-equal := to start definitions?
This syntax speaks to programmers and to mathematicians.
Could be used either inline or starting a new line.
itemize := simplest kind of list (aka bulleted list)
enumerate := items are numbered in succession
description := think "glossary" or "dictionary"
But descriptions are “in the family” of lists, so perhaps their syntax should be similar as well. (Not sure whether this is a good idea, since numbered lists do not respect this convention.)
Either way, we could consider each new line in a description list starts with, say, a tilde ‘~’.
~ itemize := simplest kind of list (aka bulleted list)
~ enumerate := items are numbered in succession
~ description := think "glossary" or "dictionary"
A dash would also be possible.
- itemize := simplest kind of list (aka bulleted list)
- enumerate := items are numbered in succession
- description := think "glossary" or "dictionary" - Term 1 := Description 1
- Term 2 := Description 2
Best idea here!
I’d even suggest adding another option as well – if a list item ends with := then it is converted to <dt> and its sublist items are converted to <dd>.
- Term 1 :=
- Description 1
- Term 2 :=
- Description 2
This would allow a single term to have multiple descriptions…
- Term 1 :=
- Description 1a
- Description 1b
…or multiple terms to share a single description.
- Term 1a :=
- Term 1b :=
- Description 1
Terms and descriptions could also be paragraph-separated, similar to loose lists.
- Term 1 := Description 1
- Term 2 := Description 2
<dl>
<p>
<dt>Term 1</dt>
<dd>Description 1</dd>
</p>
<p>
<dt>Term 2</dt>
<dd>Description 2</dd>
</p>
</dl>
- Term 1 :=
- Description 1a
- Description 1b
<dl>
<p>
<dt>Term 1</dt>
</p>
<p>
<dd>Description 1a</dd>
</p>
<p>
<dd>Description 1b</dd>
</p>
</dl>
And in non-extended Markdown, this syntax just falls back to regular lists and sublists.
I feel we are bikeshedding here. There’s already a widely used syntax for description lists, and CommonMark’s goal is to be a “strongly defined, highly compatible specification of Markdown”. Is the existing Markdown Extra syntax really such a problem that it must be replaced by a new syntax?
One other point of discussion is the question of whether it should be possible to nest description lists. Subdefinitions. This StackOverflow discussion suggests it’s valid to start a sub-description list inside a definition. Presumably, with the Markdown Extra syntax, similar indention rules can be used to CommonMark ordered and unordered lists for consistency.
Seems to me the primary motivation here for proposals that reinvent the wheel (bike wheel? I apologize for mixing metaphors…) is the need to simplify parsing.
When the parser reaches a line that starts with :, it must go back and include previous line(s) in the definition list. Backtracking 999 lines is not so convenient.
Hence, the idea of preceding a term with ~, ?, *, +, etc. This lets you know right away that a definition list starts at that point.
Alternatively, a colon might work as a preceding character, with indentation to distinguish definitions from terms:
: Term
: Another term
: Description
: Another description
Again, that would make parsing easier.
Although yes it is a different syntax and a breaking change… In existing definition list syntax, the above source produces nested definition lists and a literal colon before the first term. (Tested on https://markdown-it.github.io/)
Parsing CommonMark is already quite a complex endeavour because of the goal of preserving compatibility (see discussion in Beyond Markdown). It might be worth the added complexity and performance cost if enough documents already use the existing description list syntax.
I think we’ve got somewhat more leeway to make changes to extensions, since they aren’t yet strictly specified.
That said, CommonMark wouldn’t be CommonMark if it didn’t have wide compatibility. 
So here’s a more compatible proposal:
Each description term ends with whitespace plus :, and each subsequent description begins with : plus whitespace.
Term :
: Description
Term :
Another term :
: Description
: Another description
This makes it immediately clear where the list starts, so Markdown parsers – and human eyes – don’t need to backtrack.
In MultiMarkdown / Kramdown / Markdown Extra this syntax creates a valid description list, though with an extra space and : following each description term.
Conversely, old documents with description lists could be converted to the new syntax by appending a space and : to each term.
I would like to revive this old topic by putting in the front an even older principle of markdown. The idea (as I understand it) was for markdown to be widely compatible with the variety of usages people had when typing in plain text, such as lists, emphasis, and so on. It would then infer the intent of the writer from there. And it would only marginally impose its own markup for things like links and such.
Therefore when discussing an extension such as the “correct” syntax for descriptions lists, I think we should think of how such things are actually typed down. It seems to me that the primary, immediate, way to type description lists would be like this:
word: my description
another key: a longer description
perhaps spanning multiple lines.
maybe: one would separate its items with newlines.
At least that’s how I would write down such definition lists in a mail in plain text. I’m not sure I would try to assign the same description to multiple keys. Would I want to put multiple descriptions to the same key, I probably would write it like this:
my key:
- a first description.
- a second one,
spanning multiple lines for good measure.
So that would be the kind of syntax I’d expect to be understood by a smarter markdown. In the mean time I think it degrades gracefully when it’s written like this today.