Support for Description Lists

[ayosec]

Some parsers have an extension to support description/definition lists. In https://talk.commonmark.org/t/description-list/289 there is a proposal to add it to CommonMark. A common syntax is to put a colon at the beginning of the line.

An example from the Pandoc manual:

Term 1

:   Definition 1

Term 2 with *inline markup*

:   Definition 2

        { some code, part of Definition 2 }

    Third paragraph of definition 2.

[darkdarkfruit]

That will be better if being supported

[ngirard]

This issue should be considered critical.

Since mdBook relies on pulldown-cmark to produce its documentation, the current state of affairs is that Rust projects just cannot use definition lists within their documentations, unless they dismiss mdBook.

@ayosec has already given the 2 links that really matter here:

• the discussion related to adding description lists to CommonMark as an extension is ongoing since 2014, and probably not about to come to an end any time soon;
• the Pandoc implementation can safely be considered to be chosen wisely, since it's author, John McFarlane, is also the maintainer of the CommonMark specification.

So IMHO the next move is a no-brainer:
just choose the same syntax as Pandoc's, and implement it as an extension, so as to bring back to the Rust community a means of expression that has existed for 50 years with troff, and since 1999 with HTML !

[marcusklaas]

It seems like this should be reasonably straightforward to implement as an extension. I can mentor anyone that would like to try to do this. Shoot me a message here or on the #pulldown-cmark channel at https://xi.zulipchat.com.

[ngirard]

@marcusklaas thanks for your mentoring offer... I'm in !

[shonfeder]

Hi! I just thought I'd check in here to see if this is still in the works, or if it may be stalled out and in need of more energy/support.

[marcusklaas]

I don't think this is being worked on at the moment. It's open for any person to start work on. I am still available to assist.

[shonfeder]

@marcusklaas I'd be happy to take a crack at it. If you have any initial pointers that you think might help, please share at your leisure. Otherwise I'll circle back here once I figure out enough to form any questions, or, optimistically, to suggest my proposed implementation strategy.

[marcusklaas]

That's awesome! I only have very general pointers: first try to get a general idea of the parsing strategy (two phases) and then think of where description lists could fit in. Starting with one or two basic examples and trying to get those to parse those first seems to be another good way to get started. Hit me up here or on zulip when you have questions!

[gdamore]

Here I am in 2024, and moving to mdbook from asciidoctor, and wishing for this.