See also

For an introduction to using MyST with Sphinx, seeGet started with MyST in Sphinx.

Include rST files into a Markdown file¶

As explained inthis section, all MyST directives will parse their content as Markdown.Therefore, using the conventionalinclude directive, will parse the file contents as Markdown:

```{include} snippets/include-md.md```

Hallo I’m from a Markdown file,with a reference.

To include rST, we must first “wrap” the directive in theeval-rst directive:

```{eval-rst}.. include:: snippets/include-rst.rst```

Hallo I’m from an rST file,with a reference.

Use MyST in Jupyter Notebooks¶

TheMyST-NB tool provides a Sphinx extension for parsingJupyter Notebooks written with MyST Markdown. It includes features like automatically executing notebooks during documentation builds, storing notebook cell outputs in order to insert them elsewhere in your documentation, and more. See theMyST-NB documentation for more information.

Include a file from outside the docs folder (likeREADME.md)¶

You can include a file, including one from outside the project using e.g.:

```{include} ../README.md```

However, including a file will not usually resolve local links correctly, like![](my-image.png), since it treats the text as if it originated from the “including file”.

As of myst-parser version 0.12.7, a new, experimental feature has been added to resolve such links.You can now use for example:

Source:```{literalinclude} ../../example.md:language: md```Included:```{include} ../../example.md:relative-docs: docs/:relative-images:```

Source:

[Used in how-to](docs/sphinx/use.md)![alt](docs/_static/logo-wide.svg)

Included:

Used in how-to

The include here attempts to re-write local links, to reference them from the correct location!Therelative-docs must be given the prefix of any links to re-write, to distinguish them from sphinx cross-references.

Usesphinx.ext.autodoc in Markdown files¶

TheSphinx extensionautodoc, which pulls in code documentation from docstrings, is currently hard-coded to parse reStructuredText.It is therefore incompatible with MyST’s Markdown parser.However, the specialeval-rst directive can be used to “wrap”autodoc directives:

```{eval-rst}.. autoclass:: myst_parser.mocking.MockRSTParser    :show-inheritance:    :members: parse```

classmyst_parser.mocking.MockRSTParser(rfc2822=False,inliner=None)[source]¶

Bases:docutils.parsers.rst.Parser

RSTParser which avoids a negative side effect.

parse(inputstring:str,document:docutils.nodes.document)[source]¶

Parse the input to populate the document AST.

As with other objects in MyST, this can then be referenced:

• Using the role{py:class}`myst_parser.mocking.MockRSTParser`:myst_parser.mocking.MockRSTParser

• Using the Markdown syntax[MockRSTParser](myst_parser.mocking.MockRSTParser):MockRSTParser

Automatically create targets for section headers¶

If you’d like toautomatically generate targets for each of your section headers,check out theautosectionlabelsphinx feature. You can activate it in your Sphinx site by adding the following to yourconf.py file:

extensions=['sphinx.ext.autosectionlabel',]# Prefix document path to section labels, to use:# `path/to/file:heading` instead of just `heading`autosectionlabel_prefix_document=True

So, if you have a page atmyfolder/mypage.md (relative to your documentation root)with the following structure:

# Title## My Subtitle

Then theautosectionlabel feature will allow you to reference the section headerslike so:

{ref}`path/to/file_1:My Subtitle`

Suppress warnings¶

In general, if your build logs any warnings, you should either fix them orraise an Issue if you think the warning is erroneous.However, in some circumstances if you wish to suppress the warning you can use thesuppress_warnings configuration option.All myst-parser warnings are prepended by their type, e.g. to suppress:

# Title### Subtitle

WARNING:Non-consecutiveheaderlevelincrease;1to3[myst.header]

Add to yourconf.py:

suppress_warnings=["myst.header"]

Sphinx-specific page front matter¶

Sphinx intercepts front matter and stores them within the global environment(as discussedin the deflists documentation).There are certain front-matter keys (or their translations) that are also recognised specifically by docutils and parsed to inline Markdown:

• author

• authors

• organization

• address

• contact

• version

• revision

• status

• date

• copyright

• dedication

• abstract

A classic use-case is to specify ‘orphan’ documents, that are not specified in any toctrees.For example, inserting the following syntax at the top of a page will cause Sphinx to treat it as an orphan page:

---orphan: true---This is an orphan document, not specified in any toctrees.

Migrate pre-existing rST into MyST¶

If you’ve already got some reStructuredText files that you’d like to convert into MyST Markdown, try therst-to-myst tool, which allows you to convert single rST files to MyST markdown documents.