[Docutils-users] Docutils Markdown parser (was: Is reStructuredText required for conversion to HTML)

[Guenter M. <mi...@us...>]

Dear Cris, Omer, and everybody,

On 2020-09-23, chris sewell wrote:
> On 23 Sep 2020, at 07:37, Guenter Milde via Docutils-users
> <doc...@li...> wrote:
> > On 2020-09-23, Omer Shommo wrote:

> > > I am new to docutils. I need to know if Docutils need source files
> > > to be in reStructuredText format before converting them to HTML,
> > > LaTeX, man-pages, open-document or XML.

> > Yes, currently reStructuredText ist the only input format for Docutils.

> Well actually myst-parser is a Markdown to docutils AST renderer
> https://myst-parser.readthedocs.io, it is generally used via sphinx,
> but the base renderer is purely docutils. It also underpins
> https://myst-nb.readthedocs.io<https://myst-nb.readthedocs.io/en/latest/>
> and http://jupyterbook.org, to render Jupyter notebooks to docutils AST

Thank you for the link. When trying to install the myst-parser via pip3,
I unfortunately got a lot of unwanted requirements (one more Docutils and
Sphinx installation + several helpers).

The following proof-of-concept of a Markdown to HTML front-end therefore
relies on recommonmark::

  #!/usr/bin/env python
  # -*- coding: utf8 -*-
  # :Copyright: © 2020 Günter Milde.
  # :License: Released under the terms of the `2-Clause BSD license`_
  #
  # .. _2-Clause BSD license: https://opensource.org/licenses/BSD-2-Clause
  """
  A minimal front end to the Docutils Publisher, parsing CommonMark markdown files
  with `recommonmark` and producing HTML 5 documents.
  
  The output is also valid XML.
  """
  from docutils.core import publish_cmdline, default_description
  
  from recommonmark.parser import CommonMarkParser
  
  mdparser = CommonMarkParser()
  
  description = (u'Generate HTML5 documents from standalone '
                 u'MarkDown (CommonMark) sources.\n'
                 + default_description)
  
  publish_cmdline(parser=mdparser, writer_name='html5',
                  description=description)

This allows to convert your standalonde README.md document into HTML, say.

Similar front-ends would be easy to construct replacing the
recommonmark.parser with the myst-parser or the writer name with the name of
other standard Docutils writers.

A better integration would include a "rmd" parser module that integrates the
configurion of the markdown parser into the standard Docutils configuration
framework.
https://docutils.sourceforge.io/docs/user/config.html




Thanks,
Günter

--

A: It reverses the normal flow of conversation.
Q: What's wrong with top-posting?
A: Top-posting.
Q: What's the biggest scourge on plain text email discussions?