MyST with Docutils#

New in version 0.16.0.

Sphinx, and thus MyST-Parser, is built on top of the Docutils package. MyST-Parser offers a renderer, parser and CLI-interface for working directly with Docutils, independent of Sphinx, as described below.

Note

Since these tools are independent of Sphinx, this means they cannot parse any Sphinx or Sphinx extensions specific roles or directives.

On installing MyST-Parser, the following CLI-commands are made available:

  • myst-docutils-html: converts MyST to HTML

  • myst-docutils-html5: converts MyST to HTML5

  • myst-docutils-latex: converts MyST to LaTeX

  • myst-docutils-xml: converts MyST to docutils-native XML

  • myst-docutils-pseudoxml: converts MyST to pseudo-XML (to visualise the AST structure)

Each command can be piped stdin or take a file path as an argument:

$ myst-docutils-html --help
$ echo "Hello World" | myst-docutils-html
$ myst-docutils-html hello-world.md

The commands are based on the Docutils Front-End Tools, and so follow the same argument and options structure, included many of the MyST specific options detailed in Sphinx configuration options.

The CLI commands can also utilise the docutils.conf configuration file to configure the behaviour of the CLI commands. For example:

# These entries affect all processing:
[general]
myst-enable-extensions: deflist,linkify
myst-footnote-transition: no

# These entries affect specific HTML output:
[html writers]
embed-stylesheet: no

[html5 writer]
stylesheet-dirs: path/to/html5_polyglot/
stylesheet-path: minimal.css, responsive.css

You can also use the myst_parser.docutils_.Parser class programmatically with the Docutils publisher API:

from docutils.core import publish_string
from myst_parser.docutils_ import Parser

source = "hallo world\n: Definition"
output = publish_string(
    source=source,
    writer_name="html5",
    settings_overrides={
        "myst_enable_extensions": ["deflist"],
        "embed_stylesheet": False,
    },
    parser=Parser(),
)

Finally, you can include MyST Markdown files within a RestructuredText file, using the include directive:

.. include:: include.md
   :parser: myst_parser.docutils_

Important

The parser option requires docutils>=0.17