MyST - Markedly Structured Text

PyPI Conda

A fully-functional markdown flavor and parser for Sphinx.

MyST allows you to write Sphinx documentation entirely in markdown. MyST markdown provides a markdown equivalent of the reStructuredText syntax, meaning that you can do anything in MyST that you can do with reStructuredText. It is an attempt to have the best of both worlds: the flexibility and extensibility of Sphinx with the simplicity and readability of Markdown.

MyST has the following main features:

See Getting Started to get started.

Note

The MyST parser is in a beta stage, and may change rapidly in its implementation and machinery. Use at your own risk. If you find any issues, please report them in the MyST issues

Why MyST markdown?

While markdown is ubiquitous, it is not powerful enough for writing modern, fully-featured documentation. Some flavors of markdown support features needed for this, but there is no community standard around various syntactic choices for these features.

Sphinx is a documentation generation framework written in Python. It heavily-utilizes reStructuredText syntax, which is another markup language for writing documents. In particular, Sphinx defines two extension points that are extremely useful: in-line roles and block-level directives.

This project is an attempt at combining the simplicity and readability of Markdown with the power and flexibility of reStructuredText and the Sphinx platform. It starts with the CommonMark markdown specification, and selectively adds a few extra syntax pieces to utilize the most powerful parts of reStructuredText.

Note

The CommonMark community has been discussing an “official” extension syntax for many years now (for example, see this seven-year-old thread about directives as well as this more recent converstaion, and this comment listing several more threads on this topic).

We have chosen a “roles and directives” syntax that seems reasonable and follows other common conventions in Markdown flavors. However, if the CommonMark community ever decides on an “official” extension syntax, we will likely utilize this syntax for MyST.

Acknowledgements

The MyST markdown language and MyST parser are both supported by the open community, The Executable Book Project.