{
"cells": [
{
"cell_type": "markdown",
"metadata": {
"nbsphinx": "hidden"
},
"source": [
"This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Markdown Cells\n",
"\n",
"We can use *emphasis*, **boldface**, `preformatted text`.\n",
"\n",
"> It looks like strike-out text is not supported: ~~strikethrough~~.\n",
"\n",
"* Red\n",
"* Green\n",
"* Blue\n",
"\n",
"***\n",
"\n",
"1. One\n",
"1. Two\n",
"1. Three\n",
"\n",
"Arbitrary Unicode characters should be supported, e.g. łßō.\n",
"Note, however, that this only works if your HTML browser and your LaTeX processor provide the appropriate fonts."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Equations\n",
"\n",
"Inline equations like $\\text{e}^{i\\pi} = -1$\n",
"can be created by putting a LaTeX expression between two dollar signs, like this:\n",
"`$\\text{e}^{i\\pi} = -1$`."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"<div class=\"alert alert-info\">\n",
"\n",
"Note\n",
"\n",
"Avoid leading and trailing spaces around math expressions, otherwise errors like the following will occur when Sphinx is running:\n",
"\n",
" ERROR: Unknown interpreted text role \"raw-latex\".\n",
"\n",
"See also the [pandoc docs](https://pandoc.org/MANUAL.html#math):\n",
"\n",
"> 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.\n",
"\n",
"</div>"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Equations can also be displayed on their own line like this:\n",
"\\begin{equation}\n",
"\\int\\limits_{-\\infty}^\\infty f(x) \\delta(x - x_0) dx = f(x_0).\n",
"\\end{equation}\n",
"\n",
"This can be done by simply using one of the LaTeX math environments, like so:\n",
"\n",
"```\n",
"\\begin{equation}\n",
"\\int\\limits_{-\\infty}^\\infty f(x) \\delta(x - x_0) dx = f(x_0)\n",
"\\end{equation}\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"<div class=\"alert alert-info\">\n",
"\n",
"Note\n",
"\n",
"For equations to be shown in HTML output,\n",
"you have to specify a\n",
"[math extension](https://www.sphinx-doc.org/en/master/usage/extensions/math.html)\n",
"in your [extensions](usage.ipynb#extensions) setting, e.g.:\n",
"\n",
"```python\n",
"extensions = [\n",
" 'nbsphinx',\n",
" 'sphinx.ext.mathjax',\n",
" # ... other useful extensions ...\n",
"]\n",
"```\n",
"\n",
"</div>"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Automatic Equation Numbering\n",
"\n",
"This is not automatically enabled in Jupyter notebooks,\n",
"but you can install a notebook extension in order to enable equation numbering:\n",
"https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/equation-numbering/readme.html.\n",
"\n",
"Automatic Equation Numbering is enabled on https://nbviewer.jupyter.org/,\n",
"see e.g. the latest version of this very notebook at the link https://nbviewer.jupyter.org/github/spatialaudio/nbsphinx/blob/master/doc/markdown-cells.ipynb#Automatic-Equation-Numbering.\n",
"\n",
"When using `nbsphinx`, you can use the following `mathjax3_config` setting in your `conf.py` file\n",
"to enable automatic equation numbering in HTML output.\n",
"\n",
"```python\n",
"mathjax3_config = {\n",
" 'tex': {'tags': 'ams', 'useLabelIds': True},\n",
"}\n",
"```\n",
"\n",
"This works for Sphinx version 4 (and higher), which uses MathJax version 3.\n",
"For older Sphinx versions, the corresponding configuration looks like this:\n",
"\n",
"```python\n",
"mathjax_config = {\n",
" 'TeX': {'equationNumbers': {'autoNumber': 'AMS', 'useLabelIds': True}},\n",
"}\n",
"```\n",
"\n",
"In LaTeX output, the equations are numbered by default.\n",
"\n",
"You can use `\\label{...}` to give a unique label to an equation:\n",
"\n",
"\\begin{equation}\n",
"\\phi = \\frac{1 + \\sqrt{5}}{2}\n",
"\\label{golden-mean}\n",
"\\end{equation}\n",
"\n",
"```\n",
"\\begin{equation}\n",
"\\phi = \\frac{1 + \\sqrt{5}}{2}\n",
"\\label{golden-mean}\n",
"\\end{equation}\n",
"```\n",
"\n",
"If automatic equation numbering is enabled,\n",
"you can later reference that equation using its label.\n",
"You can use `\\eqref{golden-mean}` for a reference with parentheses: \\eqref{golden-mean},\n",
"or `\\ref{golden-mean}` for a reference without them: \\ref{golden-mean}.\n",
"\n",
"In HTML output, these equation references only work for equations within a single HTML page.\n",
"In LaTeX output, equations from other notebooks can be referenced, e.g. \\eqref{fibonacci-recurrence}."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Manual Equation Numbering\n",
"\n",
"If you prefer to assign equation numbers (or some kind of names) manually,\n",
"you can do so with `\\tag{...}`:\n",
"\n",
"\\begin{equation}\n",
"a^2 + b^2 = c^2\n",
"\\tag{99.4}\n",
"\\label{pythagoras}\n",
"\\end{equation}\n",
"\n",
"```\n",
"\\begin{equation}\n",
"a^2 + b^2 = c^2\n",
"\\tag{99.4}\n",
"\\label{pythagoras}\n",
"\\end{equation}\n",
"```\n",
"\n",
"The above equation has the number \\ref{pythagoras}."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Citations\n",
"\n",
"According to https://nbconvert.readthedocs.io/en/latest/latex_citations.html,\n",
"`nbconvert` supports citations using a special HTML-based syntax.\n",
"`nbsphinx` supports the same syntax.\n",
"\n",
"Example: <cite data-cite=\"kluyver2016jupyter\">Kluyver et al. (2016)</cite>.\n",
"\n",
"```html\n",
"<cite data-cite=\"kluyver2016jupyter\">Kluyver et al. (2016)</cite>\n",
"```\n",
"\n",
"You don't actually have to use `<cite>`,\n",
"any inline HTML tag can be used, e.g. `<strong>`:\n",
"<strong data-cite=\"perez2011python\">Python: An Ecosystem for Scientific Computing</strong>.\n",
"\n",
"```html\n",
"<strong data-cite=\"perez2011python\">Python: An Ecosystem for Scientific Computing</strong>\n",
"```\n",
"\n",
"You'll also have to define a list of references,\n",
"see [the section about references](a-normal-rst-file.rst#references).\n",
"\n",
"There is also a Notebook extension which may or may not be useful: https://github.com/takluyver/cite2c.\n",
"\n",
"### Footnote citations\n",
"\n",
"Since version `2.0.0` of sphinxcontrib-bibtex, [footnote citations](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#role-footcite) are possible. This generates footnotes for all foot-citations up to the point of the [bibliography directive](a-normal-rst-file.rst#footnote-citations), which is typically placed at the end of the source file.\n",
"\n",
"Depending on whether the documentation is rendered into HTML or into LaTeX/PDF, the citations are either placed into a bibliography as ordinary citations (HTML output) or placed into the footnotes of the citation's respective page (PDF).\n",
"\n",
"Example: <cite data-footcite=\"perez2011python\">Pérez et al. (2011)</cite>.\n",
"\n",
"```html\n",
"<cite data-footcite=\"perez2011python\">Pérez et al. (2011)</cite>\n",
"```\n",
"\n",
"As footnote references are restricted to their own Jupyter notebook or other source file, a raw nbconvert cell of reST format (see [the section about raw cells](raw-cells.ipynb)) can be added to the notebook, containing the\n",
"\n",
"```rst\n",
".. footbibliography::\n",
"```\n",
"\n",
"directive."
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
".. footbibliography::"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Alternatively, one can use the [nbsphinx epilog](prolog-and-epilog.ipynb) by setting it to, e.g.,\n",
"\n",
"```python\n",
"nbsphinx_epilog = r\"\"\"\n",
".. footbibliography::\n",
"\"\"\"\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Code\n",
"\n",
"We can also write code with nice syntax highlighting:\n",
"\n",
"```python3\n",
"print(\"Hello, world!\")\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Tables\n",
"\n",
"A | B | A and B\n",
"------|-------|--------\n",
"False | False | False\n",
"True | False | False\n",
"False | True | False\n",
"True | True | True"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Images\n",
"\n",
"Local image: \n",
"\n",
" \n",
"\n",
"Remote image: \n",
"\n",
" "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Using the HTML `<img>` tag\n",
"\n",
"The aforementioned Markdown syntax for including images\n",
"doesn't allow specifying the image size.\n",
"\n",
"If you want to control the size of the included image,\n",
"you can use the HTML\n",
"[\\<img\\>](https://www.w3.org/TR/html52/semantics-embedded-content.html#the-img-element)\n",
"element with the `width` attribute like this:\n",
"\n",
"```html\n",
"<img src=\"images/notebook_icon.png\" alt=\"Jupyter notebook icon\" width=\"300\">\n",
"```\n",
"\n",
"<img src=\"images/notebook_icon.png\" alt=\"Jupyter notebook icon\" width=\"300\">\n",
"\n",
"In addition to the `src`, `alt`, `width` and `height` attributes,\n",
"you can also use the `class` attribute,\n",
"which is simply forwarded to the HTML output (and ignored in LaTeX output).\n",
"All other attributes are ignored."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### SVG support for LaTeX\n",
"\n",
"LaTeX doesn't support SVG images, but there are Sphinx extensions that can be used for automatically converting SVG images for inclusion in LaTeX output.\n",
"\n",
"Just include one of the following options in the list of\n",
"[extensions](usage.ipynb#extensions)\n",
"in your `conf.py` file.\n",
"\n",
"* `'sphinxcontrib.inkscapeconverter'` or `'sphinxcontrib.rsvgconverter'`:\n",
" See https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter\n",
" for installation instructions.\n",
"\n",
" The external programs `inkscape` or `rsvg-convert`\n",
" (Debian/Ubuntu package `librsvg2-bin`; `conda` package `librsvg`)\n",
" are needed, respectively.\n",
"\n",
"* `'sphinx.ext.imgconverter'`:\n",
" This is a built-in Sphinx extension, see\n",
" https://www.sphinx-doc.org/en/master/usage/extensions/imgconverter.html.\n",
"\n",
" This needs the external program `convert` from *ImageMagick*.\n",
"\n",
" The disadvantage of this extension is that SVGs are converted to bitmap images.\n",
"\n",
"If one of those extensions is installed, SVG images can be used even for LaTeX output:\n",
"\n",
"\n",
"\n",
" \n",
"Remote SVG images can also be used (and will be shown in the LaTeX output):\n",
"\n",
"\n",
"\n",
" "
]
},
{
"attachments": {
"98a753bb-02aa-42e8-81da-6a5c4f9b8eb5.png": {
"image/png": "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"
},
"stickfigure.png": {
"image/png": "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"
}
},
"cell_type": "markdown",
"metadata": {},
"source": [
"## Cell Attachments\n",
"\n",
"Images can also be embedded in the notebook itself. Just drag an image file into the Markdown cell you are just editing or copy and paste some image data from an image editor/viewer.\n",
"\n",
"The generated Markdown code will look just like a \"normal\" image link, except that it will have an `attachment:` prefix:\n",
"\n",
" \n",
"\n",
"These are cell attachments: \n",
"\n",
"\n",
"\n",
"In the Jupyter Notebook, there is a speciall \"Attachments\" cell toolbar which you can use to see all attachments of a cell and delete them, if needed."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## HTML Elements (HTML only)\n",
"\n",
"It is allowed to use plain HTML elements within Markdown cells.\n",
"Those elements are passed through to the HTML output and are ignored for the LaTeX output.\n",
"Below are a few examples.\n",
"\n",
"HTML5 [audio](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio) elements can be created like this:\n",
"\n",
"```html\n",
"<audio src=\"https://example.org/audio.ogg\" controls>alternative text</audio>\n",
"```\n",
"\n",
"Example:\n",
"\n",
"<audio src=\"https://upload.wikimedia.org/wikipedia/commons/6/61/DescenteInfinie.ogg\" controls>The HTML audio element is not supported!</audio>\n",
"\n",
"\n",
"HTML5 [video](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video) elements can be created like this:\n",
"\n",
"```html\n",
"<video src=\"https://example.org/video.ogv\" controls>alternative text</video>\n",
"```\n",
"\n",
"Example:\n",
"\n",
"<video src=\"https://upload.wikimedia.org/wikipedia/commons/4/42/Shepard_Calais_1906_FrenchGP.ogv\" controls autoplay loop>The HTML video element is not supported!</video>\n",
"\n",
"The alternative text is shown in browsers that don't support those elements. The same text is also shown in Sphinx's LaTeX output.\n",
"\n",
"<div class=\"alert alert-info\">\n",
"\n",
"**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!\n",
"You should do that anyway to make the audio/video file accessible to browsers that don't support the `<audio>` and `<video>` elements.\n",
"\n",
"</div>"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Info/Warning Boxes\n",
"\n",
"<div class=\"alert alert-warning\">\n",
"\n",
"Warning\n",
"\n",
"This is an *experimental feature*!\n",
"Its usage will probably change in the future or it might be removed completely!\n",
"\n",
"</div>\n",
"\n",
"Until there is an info/warning extension for Markdown/CommonMark (see [this issue](https://github.com/jupyter/notebook/issues/1292)), such boxes can be created by using HTML `<div>` elements like this:\n",
"\n",
"```html\n",
"<div class=\"alert alert-info\">\n",
"\n",
"Note\n",
"\n",
"This is a note!\n",
"\n",
"</div>\n",
"```\n",
"\n",
"For this to work reliably, you should obey the following guidelines:\n",
"\n",
"* The `class` attribute has to be either `\"alert alert-info\"` or `\"alert alert-warning\"`, other values will not be converted correctly.\n",
"* No further attributes are allowed.\n",
"* For compatibility with CommonMark, you should add an empty line between the `<div>` start tag and the beginning of the content.\n",
"\n",
"<div class=\"alert alert-warning\">\n",
"\n",
"Warning\n",
"\n",
"While this works nicely with `nbsphinx`, JupyterLab and the Classic Jupyter Notebook,\n",
"This doesn't work correctly in `nbconvert`\n",
"and by extension on https://nbviewer.jupyter.org/ and Github's notebook preview.\n",
"\n",
"See https://github.com/jupyter/nbconvert/issues/1125.\n",
"\n",
"</div>\n",
"\n",
"<div class=\"alert alert-info\">\n",
"\n",
"Note\n",
"\n",
"The text can contain further Markdown formatting.\n",
"It is even possible to have nested boxes:\n",
"\n",
"<div class=\"alert alert-warning\">\n",
"\n",
"... but please don't *overuse* this!\n",
"\n",
"</div>\n",
"</div>"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Links to Other Notebooks\n",
"\n",
"Relative links to local notebooks can be used:\n",
"[a link to a notebook in a subdirectory](subdir/a-notebook-in-a-subdir.ipynb),\n",
"[a link to an orphan notebook](orphan.ipynb)\n",
"(latter won't work in LaTeX output, because orphan pages are not included there).\n",
"\n",
"This is how a link is created in Markdown:\n",
"\n",
"```\n",
"[a link to a notebook in a subdirectory](subdir/a-notebook-in-a-subdir.ipynb)\n",
"```\n",
"\n",
"Markdown also supports *reference-style* links:\n",
"[a reference-style link][mylink],\n",
"[another version of the same link][mylink].\n",
"\n",
"[mylink]: subdir/a-notebook-in-a-subdir.ipynb\n",
"\n",
"These can be created with this syntax:\n",
"\n",
"```\n",
"[a reference-style link][mylink]\n",
"\n",
"[mylink]: subdir/a-notebook-in-a-subdir.ipynb\n",
"```\n",
"\n",
"Links to sub-sections are also possible, e.g.\n",
"[this subsection](subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section).\n",
"\n",
"This link was created with:\n",
"\n",
"```\n",
"[this subsection](subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section)\n",
"```\n",
"\n",
"You just have to remember to replace spaces with hyphens!\n",
"\n",
"BTW, links to sections of the current notebook work, too, e.g.\n",
"[beginning of this section](#Links-to-Other-Notebooks).\n",
"\n",
"This can be done, as expected, like this:\n",
"\n",
"```\n",
"[beginning of this section](#Links-to-Other-Notebooks)\n",
"```\n",
"It's also possible to create a\n",
"[link to the beginning of the current page](#),\n",
"by simply using a `#` character:\n",
"\n",
"```\n",
"[link to the beginning of the current page](#)\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Links to `*.rst` Files (and Other Sphinx Source Files)\n",
"\n",
"Links to files whose extension is in the configuration value [source_suffix](https://www.sphinx-doc.org/en/master/config.html#confval-source_suffix), will be converted to links to the generated HTML/LaTeX pages. Example: [A reStructuredText file](a-normal-rst-file.rst).\n",
"\n",
"This was created with:\n",
"\n",
"```\n",
"[A reStructuredText file](a-normal-rst-file.rst)\n",
"```\n",
"\n",
"Links to sub-sections are also possible. Example: [Sphinx Directives](a-normal-rst-file.rst#sphinx-directives-for-info-warning-boxes).\n",
"\n",
"This was created with:\n",
"\n",
"```\n",
"[Sphinx Directives](a-normal-rst-file.rst#sphinx-directives-for-info-warning-boxes)\n",
"```\n",
"\n",
"<div class=\"alert alert-info\">\n",
"\n",
"Note\n",
"\n",
"Sphinx section anchors are different from Jupyter section anchors!\n",
"To create a link to a subsection in an `.rst` file (or another non-notebook source file), you not only have to replace spaces with hyphens, but also slashes and some other characters.\n",
"In case of doubt, just check the target HTML page generated by Sphinx.\n",
"\n",
"</div>"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Links to Local Files\n",
"\n",
"Links to local files (other than Jupyter notebooks and other Sphinx source files) are also possible, e.g. [requirements.txt](requirements.txt).\n",
"\n",
"This was simply created with:\n",
"\n",
"```\n",
"[requirements.txt](requirements.txt)\n",
"```\n",
"\n",
"The linked files are automatically copied to the HTML output directory.\n",
"For LaTeX output, links are created,\n",
"but the files are not copied to the target directory."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Links to Domain Objects\n",
"\n",
"Links to [Sphinx domain objects](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html) (such as a Python class or JavaScript function) are also possible. For example:\n",
"[example_python_function()](a-normal-rst-file.rst#example_python_function).\n",
"\n",
"This was created with:\n",
"\n",
"```\n",
"[example_python_function()](a-normal-rst-file.rst#example_python_function)\n",
"```\n",
"\n",
"This is especially useful for use with the Sphinx [autodoc](https://www.sphinx-doc.org/en/master/ext/autodoc.html) extension!"
]
}
],
"metadata": {
"celltoolbar": "Raw Cell Format",
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.9.2"
}
},
"nbformat": 4,
"nbformat_minor": 4
}