FAQ#
1. How-tos#
These sections describe some common scenarios and use-cases for writing MyST with Sphinx.
1.1. Include rST files into a Markdown file#
As explained in this section, all MyST directives will parse their content as Markdown.
Therefore, using the conventional include
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 the eval-rst directive:
```{eval-rst}
.. include:: snippets/include-rst.rst
```
Hallo Iâm from an rST file, with a reference.
1.2. Include Markdown files into an rST file#
To include a MyST file within a ReStructuredText file, we can use the parser
option of the include
directive:
.. include:: include.md
:parser: myst_parser.sphinx_
Important
The parser
option requires docutils>=0.17
1.3. Use MyST in Jupyter Notebooks#
The MyST-NB tool provides a Sphinx extension for parsing Jupyter 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 the MyST-NB documentation for more information.
1.4. Include a file from outside the docs folder (like README.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/faq/index.md)
![alt](docs/_static/logo-wide.svg)
Included:
The include here attempts to re-write local links, to reference them from the correct location!
The relative-docs
must be given the prefix of any links to re-write, to distinguish them from sphinx cross-references.
Important
The current functionality only works for Markdown style images and links.
If you encounter any issues with this feature, please donât hesitate to report it.
1.5. Use sphinx.ext.autodoc
in Markdown files#
See Documenting whole APIs for this information.
1.6. Automatically create targets for section headers#
Added in version 0.13.0: See Implicit targets for this information.
1.7. Suppress warnings#
See Build Warnings for this information.
1.8. Sphinx-specific page front matter#
Sphinx intercepts front matter and stores them within the global environment (as discussed in the sphinx 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.
1.9. Migrate pre-existing rST into MyST#
If youâve already got some reStructuredText files that youâd like to convert into MyST Markdown, try the rst-to-myst
tool, which allows you to convert single rST files to MyST markdown documents.
2. Disable Markdown syntax for the parser#
If youâd like to either enable or disable custom markdown syntax, use myst_disable_syntax
.
Anything in this list will no longer be parsed by the MyST parser.
For example, to disable the emphasis
in-line syntax, use this configuration:
myst_disable_syntax = ["emphasis"]
emphasis syntax will now be disabled. For example, the following will be rendered without any italics:
*emphasis is now disabled*
For a list of all the syntax elements you can disable, see the markdown-it parser guide.
3. Common errors and questions#
These are common issues and gotchas that people may experience when using the MyST Sphinx extension.
3.1. What markup language should I use inside directives?#
If you need to parse content inside of another block of content (for example, the content inside a note directive), note that the MyST parser will be used for this nested parsing as well.
3.2. Why doesnât my role/directive recognize markdown link syntax?#
There are some roles/directives that hard-code syntax into
their behavior. For example, many roles allow you to supply titles for links like so:
{role}`My title <myref>`
. While this looks like reStructuredText, the role may
be explicitly expecting the My title <myref>
structure, and so MyST will behave the same way.