\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 `
` start tag and the beginning of the content.\n",
"\n",
"
\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",
"
\n",
"\n",
"
\n",
"\n",
"Note\n",
"\n",
"The text can contain further Markdown formatting.\n",
"It is even possible to have nested boxes:\n",
"\n",
"
\n",
"\n",
"... but please don't *overuse* this!\n",
"\n",
"
\n",
"
"
]
},
{
"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",
"And if there are double quotes in the section title,\n",
"you'll have to replace them with `%22`,\n",
"like e.g. `#That's-a-%22Strange%22-Section` in this link:\n",
"[a section with \"strange\" characters](subdir/a-notebook-in-a-subdir.ipynb#That's-a-%22Strange%22-Section).\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",
"\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",
"
\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",
"
"
]
},
{
"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!\n",
"\n",
"In some situations, you might prefer to have the default Sphinx formatting and checking in place when linking to domain objects.\n",
"In such a case,\n",
"[raw cells in \"reST\" format](raw-cells.ipynb#reST)\n",
"could be an alternative worthwhile considering.\n",
"They allow one to use any kind of Sphinx roles and directives inside a Jupyter Notebook."
]
}
],
"metadata": {
"celltoolbar": "Raw Cell Format",
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"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.11.2"
}
},
"nbformat": 4,
"nbformat_minor": 4
}