MyST - Markedly Structured Text¶
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:
Call Sphinx directives and roles from within Markdown, allowing you to extend your document via Sphinx extensions.
Extended Markdown syntax for useful rST features, such as line commenting and footnotes.
A Sphinx-independent parser of MyST markdown that can be extended to add new functionality and outputs for MyST.
A superset of CommonMark markdown. Any CommonMark markdown (such as Jupyter Notebook markdown) is natively supported by the MyST parser.
You may use MyST markdown in addition to using reStructuredText in Sphinx. See Getting Started to get started.
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
- Getting Started
- The MyST Syntax Guide
- How-To Guides
- Frequently Asked Questions
- Python API
- The Parser
- Example pages
- Contribute to MyST
- MyST-Parser API reference
- GitHub repo
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.
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.