How-To Guides¶
This page describes several common uses of MyST parser and how to accomplish them.
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.
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:
```{include-literal} ../../example.md
:language: md
```
Included:
```{include} ../../example.md
:relative-docs: docs/
:relative-images:
```
Source:
[Used in how-to](docs/using/howto.md)
![alt](docs/_static/logo.png)
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.
Use sphinx.ext.autodoc
in Markdown files¶
The Sphinx extension autodoc
, 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 special eval-rst
directive can be used to “wrap” autodoc
directives:
```{eval-rst}
.. autoclass:: myst_parser.mocking.MockRSTParser
:show-inheritance:
:members: parse
```
-
class
myst_parser.mocking.
MockRSTParser
(rfc2822=False, inliner=None)[source]¶ Bases:
docutils.parsers.rst.Parser
RSTParser which avoids a negative side effect.
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
Warning
This expects docstrings to be written in reStructuredText. We hope to support Markdown in the future, see GitHub issue #228.
Show backticks inside raw markdown blocks¶
If you’d like to show backticks inside of your markdown, you can do so by nesting them in backticks of a greater length. Markdown will treat the outer-most backticks as the edges of the “raw” block and everything inside will show up. For example:
`` `hi` ``
will be rendered as: `hi`
and
````
```
hi
```
````
will be rendered as:
```
hi
```
Automatically create targets for section headers¶
Important
New in v0.13.0
✨, myst-parser now provides a separate implementation of autosectionlabel
, which implements GitHub Markdown style bookmark anchors, like [](file.md#header-anchor)
.
See the Auto-generated header anchors section of extended syntaxes.
If you’d like to automatically generate targets for each of your section headers,
check out the autosectionlabel
sphinx feature. You can activate it in your Sphinx site by adding the following to your
conf.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 at myfolder/mypage.md
(relative to your documentation root)
with the following structure:
# Title
## My Subtitle
Then the autosectionlabel
feature will allow you to reference the section headers
like so:
{ref}`path/to/file_1:My Subtitle`
Suppress warnings¶
In general, if your build logs any warnings, you should either fix them or raise an Issue if you think the warning is erroneous.
However, in some circumstances if you wish to suppress the warning you can use the suppress_warnings
configuration option.
All myst-parser warnings are prepended by their type, e.g. to suppress:
# Title
### Subtitle
WARNING: Non-consecutive header level increase; 1 to 3 [myst.header]
Add to your conf.py
:
suppress_warnings = ["myst.header"]