docutils.md

(myst-docutils)=

MyST with Docutils

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 .

:::{dropdown} Shared Docutils CLI 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 {py:class}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_

The `parser` option requires `docutils>=0.17`