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:
- A markdown parser for Sphinx
You can write your entire Sphinx documentation in Markdown.
- 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
This 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.
- Getting Started
- The MyST Syntax Guide
- Optional MyST Syntaxes
- 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.