The way I see Markdown is as a great intermediate format. Which means that you
can use it to author and archive content which is read in a different format.
Another such intermediate format is LaTeX. The main difference between the two
is that while Markdown is lightweight and easy to learn, LaTeX is highly
extensible and powerful. By design the two are quite orthogonal when it comes
to uses and there is no sense in trying to make one more like the other or vice
The output formats are usually less readable (and writable) like PDF, XML
(HTML, EPUB, Docx, OpenOffice etc.), troff, rtf, PostScript etc. So it is very
important that conversion is easy and straight forward.
Originally Markdown was intended to only produce HTML but with time it was
discovered that it can be useful in a variety of settings where the output is
not HTML. Which gets me to the problem.
Right now CommonMark includes renderers to XML, troff and LaTeX. As described
above, the XML output is very good because Markdown was written with HTML in
mind. For other languages it would be nice if the conversion would be
facilitated in a similar manner.
Now since each target language has its idiosyncrasies, it is sometimes hard to
do something in Markdown and get the expected results after conversion.
The proposal has two parts. First to extend the core syntax to include
definition lists which are needed for full compatibility with the groff man
macro package and second to allow embedding languages other than HTML.
- Right now, writing man-pages in Markdown is almost impossible in CommonMark
since it does not specify definition lists which would correspond to the
.IPmacro in man(7). This is for instance used when describing flags or
- In general it would be nice if an arbitrary language could be embedded into
the Markdown source (troff, LaTeX, etc.). This would of course be terrible
(mostly) to read and entirely against the philosophy of Markdown, but it is
already done with HTML to enable special properties that would otherwise be
lost in conversion so it would only be natural to also allow that for other
languages too. In the example of man-pages, it could allow the use of other
macro packages like mdoc (the BSD endorsed way to write man-pages). Also
in this example one could then generate the html from the man-pages
themselves or use a preprocessor to substitute some parts of the Markdown
with the raw troff. In any way embedding parts of the target language
directly into the Markdown document could be very beneficial for conversion.