[Docutils-users] Docutils can do Markdown, too

[Tony Narlock]

reStructuredText is covered by the Documentation Utilities.


What about Markdown? Docutils has all the tools needed to parse it, and
there is activity in the area.

A few years ago, remarkdown (https://github.com/sgenoud/remarkdown) sprung
up. As of this writing the last commit is Oct 14, 2014.

A new fork, recommonmark, implementing CommonMark (http://commonmark.org/)
specification of MarkDown emerged recently. You can try it out at
https://github.com/rtfd/recommonmark.

Both remarkdown and recommonmark return a docutils document tree (
http://docutils.sourceforge.net/docs/ref/doctree.html#document).

recommonmark is held with the ReadTheDocs project. Theoretically this could
give documentation writers the ability to use Markdown with sphinx.

There are exciting projects underway with docutils (including Kivy's
kiv.uix.rst module). It's a good time for docutils!

[Stefan Merten]

Hi!

Post by Tony Narlock
Both remarkdown and recommonmark return a docutils document tree (
http://docutils.sourceforge.net/docs/ref/doctree.html#document).

Which opens a way to produce reStructuredText from Markdown by using
`xml2rst`.


Grüße

Stefan

[Guenter Milde]

Post by Stefan Merten
Hi!

Post by Tony Narlock
Both remarkdown and recommonmark return a docutils document tree (
http://docutils.sourceforge.net/docs/ref/doctree.html#document).

If so, they could be used as alternative parsers:

* Up to now, Docutils only ships with the standard "rst" parser, however,
the framework for alternative parsers exists.

* a front-end could set up the parser from either of these projects +
standard Docutils transforms and standard Docutils writers.

This could either be a suite of front-ends (md2html, md2html5, md2latex,
md2xml, md2odt, md2manpage ...) or one "metawriter" with mandatory writer
argument (``mdocutils html5 mydoc.md``)

It would only be that easy, if the "docutils document tree" returned by
the markdown parser not only uses Docutils nodes and elements but also
follows all the documented and nondocumented conventions and
restrictions.

Otherwise, we might either cooperate with the upstream authors to fit the
alternative parsers into Docutils or add a wrapper layer including
transfomrs required to "sanitize" the document tree before handing it to the
standard transforms and writer.

Post by Stefan Merten
Which opens a way to produce reStructuredText from Markdown by using
`xml2rst`.

One more interesting option
(and one more incentive to add an "rst" writer to Docutils). :-)