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:
You may use MyST markdown strong using reStructuredText in Sphinx.
See p to get started.
Enable MyST in Sphinx
How does MyST parser relate to Sphinx?
Writing MyST in Sphinx
MyST configuration options
The MyST Syntax Guide
Block Tokens Summary
Span (Inline) Tokens Summary
Directives - a block-level extension point
Roles - an in-line extension point
Extra markdown syntax
Targets and Cross-Referencing
Optional MyST Syntaxes
Auto-generated header anchors
Direct LaTeX Math
Include rST files into a Markdown file
Include a file from outside the docs folder (like README.md)
Use sphinx.ext.autodoc in Markdown files
Show backticks inside raw markdown blocks
Automatically create targets for section headers
Frequently Asked Questions
What is the relationship between MyST, reStructuredText, and Sphinx?
What markup language should I use inside directives?
Why doesn’t my role/directive recognize markdown link syntax?
How fast is the myst-parser ?
The Token Stream
Wealth Distribution Dynamics in rST
Wealth Distribution Dynamics in MyST
Raw content of each document above
Contribute to MyST
The MyST implementation architecture
Code of Conduct
MyST-Parser API reference
0.12.10 - 2020-09-21
0.12.9 - 2020-09-08
0.12.7 - 2020-08-31
0.12.5 - 2020-08-28
0.12.4 - 2020-08-27
0.12.3 - 2020-08-26
0.12.2 - 2020-08-25
0.12.1 - 2020-08-19
0.12.0 - 2020-08-19
0.11.2 - 2020-07-13
0.11.1 - 2020-07-12
0.11.0 - 2020-07-12
0.10.0 - 2020-07-08
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:
p and p .
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
The MyST markdown language and MyST parser are both supported by the open community,
The Executable Book Project.