Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from http://stackoverflow.com/questions/2471804/using-sphinx-with-markdown-instead-of-rst below:

python - Using Sphinx with Markdown instead of reST

I recommend using MyST Markdown. This is a flavor of Markdown that was designed to bring in the major features of reStructuredText. MyST stands for Markedly Structured Text, and can be thought of as "rST but with Markdown".

MyST is a superset of the CommonMark standard, and it is defined as a collection of discrete extensions to CommonMark via the markdown-it-py package). This means that CommonMark syntax works out-of-the-box with MyST, but you can also use more syntax features if you wish.

MyST has syntax for virtually every feature in reStructuredText, and it is tested against the full Sphinx test suite to ensure that the same functionality can be re-created. For example:

Here is how you write a directive in MyST:

```{directivename} directive options
:key: value
:key2: value2

Directive content
```

And here is how you write a role in MyST

Here's some text and a {rolename}`role content`

The Sphinx parser for MyST Markdown also has some nice Sphinx-specific features, like using Markdown link syntax ([some text](somelink)) to also handle cross-references in Sphinx. So for example, you can define a label in MyST, and reference it, like so:

(my-label)=
# My header

Some text and a [cross reference](my-label).

For a more complete list of MyST Markdown syntax, a good reference is the Jupyter Book cheatsheet, which has a list of many common document needs and the respective MyST syntax to accomplish it. (MyST was created as a component of Jupyter Book, though it exists as a totally standalone project from a technical perspective).

MyST is now the recommended Markdown tool for Sphinx in the Sphinx docs as well as the ReadTheDocs documentation.

To add the MyST Parser to your Sphinx documentation, simply do the following:

pip install myst-parser

And in conf.py, add:

extensions = [
  ...
  "myst_parser",
  ...
]

Your Sphinx documentation will now be able to parse CommonMark markdown as well as the extended MyST Markdown syntax! Check out the MyST Documentation for more information!

I hope that this helps clarify some things!

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4