doc/markdown-cells.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": "hidden"
   },
   "source": [
    "This notebook is part of the `nbsphinx` documentation: http://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",
    "Equations can be formatted really nicely, either inline, like $\\text{e}^{i\\pi} = -1$, or on a separate line, like\n",
    "\n",
    "\\begin{equation}\n",
    "\\int_{-\\infty}^\\infty f(x) \\delta(x - x_0) dx = f(x_0)\n",
    "\\end{equation}\n",
    "\n",
    "*Note:* 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](http://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."
   ]
  },
  {
   "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",
    "PNG file (local): ![Jupyter notebook icon](images/notebook_icon.png)\n",
    "\n",
    "SVG file (local): ![Python logo](images/python_logo.svg)\n",
    "\n",
    "PNG file (remote): ![Python logo (remote)](https://www.python.org/static/img/python-logo-large.png)\n",
    "\n",
    "SVG file (remote): ![Jupyter logo (remote)](http://jupyter.org/assets/nav_logo.svg)"
   ]
  },
  {
   "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:** 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-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",
    "```"
   ]
  },
  {
   "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](http://www.sphinx-doc.org/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 (HTML only)\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, no link is created."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Links to Domain Objects\n",
    "\n",
    "Links to [Sphinx domain objects](http://www.sphinx-doc.org/domains.html) (such as a Python class or JavaScript function) are also possible. For example: [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](http://www.sphinx-doc.org/ext/autodoc.html) extension!"
   ]
  }
 ],
 "metadata": {
  "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.6.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}