The MyST implementation architecture

The MyST implementation architecture#

This page describes implementation details to help you understand the structure of the project.

1.  A Renderer for markdown-it tokens#

At a high level, the MyST parser is an extension of the Markdown-It-Py project. Markdown-It-Py is a well-structured Python parser for CommonMark text. It also defines an extension point to include more syntax in parsed files. The MyST parser uses this extension point to define its own syntax options (e.g., for Sphinx roles and directives).

The result of this parser is a markdown-it token stream.

2.  A docutils renderer#

The MyST parser also defines a docutils renderer for the markdown-it token stream. This allows us to convert parsed elements of a MyST markdown file into docutils.

3.  A Sphinx parser#

Finally, the MyST parser provides a parser for Sphinx, the documentation generation system. This parser does the following:

  • Parse markdown files with the markdown-it parser, including MyST specific plugins

  • Convert these files into docutils objects using the MyST docutils renderer

  • Provide these to Sphinx in order to use in building your site.