migrate-rest-myst.md

How to migrate from reStructuredText to MyST Markdown

In this guide, you will find how you can start writing Markdown in your existing reStructuredText project, or migrate it completely.

Sphinx is usually associated with reStructuredText, the markup language {pep}designed for the CPython project in the early '00s <287>. However, for quite some time Sphinx has been compatible with Markdown as well, thanks to a number of extensions.

The most powerful of such extensions is {doc}MyST-Parser <myst-parser:index>, which implements a CommonMark-compliant, extensible Markdown dialect with support for the Sphinx roles and directives that make it so useful.

If, instead of migrating, you are starting a new project from scratch, have a look at {doc}myst-parser:intro. If you are starting a project for Jupyter, you can start with Jupyter Book, which uses MyST-Parser, see the official Jupyter Book tutorial: {doc}jupyterbook:start/your-first-book

How to write your content both in reStructuredText and MyST

It is useful to ask whether a migration is necessary in the first place. Doing bulk migrations of large projects with lots of work in progress will create conflicts for ongoing changes. On the other hand, your writers might prefer to have some files in Markdown and some others in reStructuredText, for whatever reason. Luckily, Sphinx supports reading both types of markup at the same time without problems.

To start using MyST in your existing Sphinx project, first install the myst-parser Python package and then enable it on your configuration:

:caption: conf.py
:emphasize-lines: 4

extensions = [
    # Your existing extensions
    ...,
    "myst_parser",
]

Your reStructuredText documents will keep rendering, and you will be able to add MyST documents with the .md extension that will be processed by MyST-Parser.

As an example, this guide is written in MyST while the rest of the Read the Docs documentation is written in reStructuredText.

By default, MyST-Parser registers the `.md` suffix for MyST source files.
If you want to use a different suffix, you can do so by changing your
`source_suffix` configuration value in `conf.py`.

How to convert existing reStructuredText documentation to MyST

To convert existing reST documents to MyST, you can use the rst2myst CLI script shipped by {doc}rst-to-myst:index. The script supports converting the documents one by one, or scanning a series of directories to convert them in bulk.

After {doc}installing `rst-to-myst` <rst-to-myst:index>, you can run the script as follows:

$ rst2myst convert docs/source/index.rst  # Converts index.rst to index.md
$ rst2myst convert docs/**/*.rst  # Convert every .rst file under the docs directory

This will create a .md MyST file for every .rst source file converted.

How to modify the behaviour of rst2myst

The rst2myst accepts several flags to modify its behavior. All of them have sensible defaults, so you don't have to specify them unless you want to.

These are a few options you might find useful:

{option}-d, --dry-run <rst-to-myst:rst2myst-convert.--dry-run> : Only verify that the script would work correctly, without actually writing any files.

{option}-R, --replace-files <rst-to-myst:rst2myst-convert.--replace-files> : Replace the .rst files by their .md equivalent, rather than writing a new .md file next to the old .rst one.

You can read the full list of options in {doc}the `rst2myst` documentation <rst-to-myst:cli>.

How to enable optional syntax

Some reStructuredText syntax will require you to enable certain MyST plugins. For example, to write reST definition lists, you need to add a myst_enable_extensions variable to your Sphinx configuration, as follows:

:caption: conf.py
myst_enable_extensions = [
    "deflist",
]

You can learn more about {doc}other MyST-Parser plugins <myst-parser:syntax/optional> in their documentation.

How to write reStructuredText syntax within MyST

There is a small chance that rst2myst does not properly understand a piece of reST syntax, either because there is a bug in the tool or because that syntax does not have a MyST equivalent yet. For example, {ref}as explained in the documentation <myst-parser:howto/autodoc>, the sphinx.ext.autodoc extension is incompatible with MyST.

Fortunately, MyST supports an eval-rst directive that will parse the content as reStructuredText, rather than MyST. For example:

```{eval-rst}
.. note::

   Complete MyST migration.

```

will produce the following result:

.. note::

   Complete MyST migration.

As a result, this allows you to conduct a gradual migration, at the expense of having heterogeneous syntax in your source files. In any case, the HTML output will be the same.