Markdown Cells

We can use emphasis, boldface, preformatted text.

It looks like strike-out text is not supported: [STRIKEOUT:strikethrough].

• Red
• Green
• Blue

---

1. One
2. Two
3. Three

Equations

Equations can be formatted really nicely, either inline, like \(\text{e}^{i\pi} = -1\), or on a separate line, like

Note: Avoid leading and trailing spaces around math expressions, otherwise errors like the following will occur when Sphinx is running:

ERROR: Unknown interpreted text role "raw-latex".

See also the pandoc docs:

Anything between two $ characters will be treated as TeX math. The opening $ must have a non-space character immediately to its right, while the closing $ must have a non-space character immediately to its left, and must not be followed immediately by a digit.

Code

We can also write code with nice syntax highlighting:

print("Hello, world!")

Tables

A	B	A and B
False	False	False
True	False	False
False	True	False
True	True	True

Images

PNG file (local):

SVG file (local):

PNG file (remote):

SVG file (remote):

HTML Elements (HTML only)

It is allowed to use plain HTML elements within Markdown cells. Those elements are passed through to the HTML output and are ignored for the LaTeX output. Below are a few examples.

HTML5 audio elements can be created like this:

<audio src="https://example.org/audio.ogg" controls>alternative text</audio>

Example:

HTML5 video elements can be created like this:

<video src="https://example.org/video.ogv" controls>alternative text</video>

Example:

The alternative text is shown in browsers that don’t support those elements. The same text is also shown in Sphinx’s LaTeX output.

Note: You can also use local files for the <audio> and <video> elements, but you have to create a link to the source file somewhere, because only then are the local files copied to the HTML output directory! You should do that anyway to make the audio/video file accessible to browsers that don’t support the <audio> and <video> elements.

Info/Warning Boxes

Warning:

This is an experimental feature! Its usage will probably change in the future or it might be removed completely!

Until there is an info/warning extension for Markdown/CommonMark (see this issue), such boxes can be created by using HTML <div> elements like this:

<div class="alert alert-info">

**Note:** This is a note!

</div>

For this to work reliably, you should obey the following guidelines:

• The class attribute has to be either "alert alert-info" or "alert alert-warning", other values will not be converted correctly.
• No further attributes are allowed.
• For compatibility with CommonMark, you should add an empty line between the <div> start tag and the beginning of the content.

Note:

The text can contain further Markdown formatting. It is even possible to have nested boxes:

... but please don’t overuse this!

Links to Other Notebooks

Relative links to local notebooks can be used: a link to a notebook in a subdirectory, a link to an orphan notebook (latter won’t work in LaTeX output, because orphan pages are not included there).

This is how a link is created in Markdown:

[a link to a notebook in a subdirectory](subdir/a-notebook-in-a-subdir.ipynb)

Markdown also supports reference-style links: a reference-style link, another version of the same link.

These can be created with this syntax:

[a reference-style link][mylink]

[mylink]: subdir/a-notebook-in-a-subdir.ipynb

Links to sub-sections are also possible, e.g. this subsection.

This link was created with:

[this subsection](subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section)

You just have to remember to replace spaces with hyphens!

BTW, links to sections of the current notebook work, too, e.g. beginning of this section.

This can be done, as expected, like this:

[beginning of this section](#Links-to-Other-Notebooks)

Links to *.rst Files (and Other Sphinx Source Files)

Links to files whose extension is in the configuration value source_suffix, will be converted to links to the generated HTML/LaTeX pages. Example: A reStructuredText file.

This was created with:

[A reStructuredText file](a-normal-rst-file.rst)

Links to sub-sections are not (yet?) possible.

Links to Local Files (HTML only)

Links to local files (other than Jupyter notebooks and other Sphinx source files) are also possible, e.g. requirements.txt.

This was simply created with:

[requirements.txt](requirements.txt)

The linked files are automatically copied to the HTML output directory. For LaTeX output, no link is created.