1.10.7. Tips for working with Markdown
Markdown is great for very simple documentation files—it's much easier to write and read Markdown source than reStructuredText source.
Note that our documentation build system uses the MyST Markdown parser. MyST is a special "flavor" of Markdown that has a lot of reStructuredText-like features added to it; see the guide to MyST Markdown syntax here, although note that we don't include a lot of the referenced extensions.
If you use VS Code, you may want to install the MyST-Markdown extension to get syntax highlighting, auto-complete, and improved rendering in the VS Code previewer.
1.10.7.1. Markdown: Cross-references
You can link to Markdown section headers by adding a label before the header:
(md-cross-references)=
## Markdown: Cross-references
and then referring to it like [link to section headers](#md-cross-references). You can also have the display text just be the title of the relevant section—e.g., Markdown: Cross-references—by doing [](#md-cross-references).
That linking syntax also works for links to section labels in reStructuredText files: [section labels in reStructuredText files](#rst-cross-references).
1.10.7.2. Markdown: Math
Inline math can be achieved with the typical Markdown syntax of just surrounding your expression with dollar signs. E.g., \(y = mx + b\):
E.g., $y = mx + b$:
You can also use Markdown's math block syntax for big equations on their own lines, with an optional label after the second $$ that will give it a number and make it cross-referenceable:
$$
y = mx + b
$$ (my-equation-label)
Then you can get the equation number (1.10.1) like so:
Then you can get the equation number {eq}`my-equation-label` like so:
1.10.7.3. Markdown: Comments
If you want to add some text that's only visible in the documentation source file, you can put a % at the beginning of a line. E.g.:
% This will not appear on the webpage.
1.10.7.4. Markdown: Tables
Markdown tables are supported. See GitHub's "Organizing information with tables" for more info.
1.10.7.5. Markdown: Admonitions
Admonitions are rendered as special "call-out" boxes. The general syntax is:
```{admonition} This is the title of a generic admonition
It needs a title specified. Synonyms you can put in the `{}` instead of `admonition` include `note` and `seealso`; if you use one of those, you can't specify a title. In fact, `admonition` is the only type of admonition that you can specify a custom title for.
```
This is the title of a generic admonition
It needs a title specified. Synonyms you can put in the {} instead of admonition include note and seealso; if you use one of those, you can't specify a title. In fact, admonition is the only type of admonition that you can specify a custom title for.
There are also a number of built-in admonition types that get their own special rendering:
```{attention}
The reader should pay special attention to this. Synonyms you can put in the `{}` instead of `attention` include `caution` and `warning`.
```
Attention
The reader should pay special attention to this. Synonyms you can put in the {} instead of attention include caution and warning.
```{danger}
This tells the reader about something dangerous. You can also put `error` in the `{}` instead of `danger`.
```
Danger
This tells the reader about something dangerous. You can also put error in the {} instead of danger.
```{hint}
Here's a hint. Synonyms you can put in the `{}` instead of `hint` include `important` and `tip`.
```
Hint
Here's a hint. Synonyms you can put in the {} instead of hint include important and tip.
1.10.7.6. Markdown: Embedding a different Markdown file
It can be useful to embed one Markdown file within another. This is done in this documentation documentation, for instance, to embed doc/source/users_guide/working-with-documentation/embed-build-cmd.md on three different pages.
As an example, here's what an embedding looks like:
That becomes:
```{include} embed-example-markdown.md
```
That becomes:
Everything in this paragraph is just the contents of
doc/source/users_guide/working-with-documentation/embed-example-markdown.md. It's in the same directory
as the "Tips for working with Markdown" source file, so we only had to specify the
filename. If it were in a different directory, we would specify the path relative to "Tips for
working with Markdown". (Note that this file does NOT follow the "no line breaks within
paragraphs" style convention; this is purely for readability of the embedded text.)
See the MyST Markdown documentation for the "include" directive for more information.
You can also embed literal contents of any file without the rendering:
That becomes the literal contents:
```{literalinclude} embed-example-markdown.md
```
That becomes the literal contents:
---
orphan: true
---
Everything in this paragraph is just the contents of
`doc/source/users_guide/working-with-documentation/embed-example-markdown.md`. It's in the same directory
as the "Tips for working with Markdown" source file, so we only had to specify the
filename. If it were in a different directory, we would specify the path relative to "Tips for
working with Markdown". (Note that this file does NOT follow the "no line breaks within
paragraphs" style convention; this is purely for readability of the embedded text.)
(The first three lines are to indicate to Sphinx that it's okay for that file to not be included in any Table of Contents; i.e., to suppress the WARNING: document isn't included in any toctree [toc.not_included] build message.)
You can also get fancy:
```{literalinclude} embed-example-python.py
:language: python
:linenos:
```
Becomes (note syntax highlighting):
1"""
2This is just an example Python file that will be literalinclude'ed
3"""
4
5print("Hello world")
6my_list = ["foo", "bar"]
And
```{literalinclude} embed-example-python.py
:language: python
:linenos:
:start-at: print
:lineno-match:
```
Becomes:
5print("Hello world")
6my_list = ["foo", "bar"]
See the MyST Markdown documentation for the include directive for more information (all options apply to literalinclude as well).