Normal reStructuredText Files
This is a normal RST file.
Links to Notebooks (and Other Sphinx Source Files)
Links to Sphinx source files can be created like normal Sphinx hyperlinks,
just using a relative path to the local file: link.
using a relative path to the local file: link_.
.. _link: subdir/a-notebook-in-a-subdir.ipynb
If the link text has a space (or some other strange character) in it, you have
to surround it with backticks: a notebook link.
surround it with backticks: `a notebook link`_.
.. _a notebook link: subdir/a-notebook-in-a-subdir.ipynb
You can also use an anonymous hyperlink target, like this: link.
If you have multiple of those, their order matters!
like this: link__.
Finally, you can use Embedded URIs, like this
like this `link <subdir/a-notebook-in-a-subdir.ipynb>`_.
These links should also work on Github and in other rendered
Links to subsections are also possible by adding a hash sign (
#) and the
section title to any of the above-mentioned link variants.
You have to replace spaces in the section titles by hyphens.
For example, see this subsection.
For example, see this subsection_.
.. _subsection: subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section
Links to Notebooks, Ye Olde Way
In addition to the way shown above, you can also create links to notebooks (and
other Sphinx source files) with
This has some disadvantages:
It is arguably a bit more clunky.
:ref: is a Sphinx feature, the links don’t work on Github and
other rendered reStructuredText pages that use plain old
It also has one important advantage:
A link with automatic title looks like this:
Notebooks in Sub-Directories.
But you can also provide
your own link title.
:ref:`your own link title </subdir/a-notebook-in-a-subdir.ipynb>`
However, if you want to use your own title, you are probably better off using
the method described above in
Links to Notebooks (and Other Sphinx Source Files).
Links to subsections are also possible, e.g.
(the subsection title is used as link text) and
These links were created with:
:ref:`alternative text </subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section>`
Sphinx Directives for Info/Warning Boxes
This is an experimental feature!
Its usage may change in the future or it might disappear completely, so
don’t use it for now.
With a bit of luck, it will be possible (some time in the future) to create
info/warning boxes in Markdown cells, see
If this ever happens,
nbsphinx will provide directives for creating such
For now, there are two directives available:
This is how an info box looks like:
This is an info box.
It may include nested formatting, even another info/warning box:
Warning: You should probably not use nested boxes!
This is just for testing domain object links.
foo (str) – Example string parameter
There are different ways of handling references, for example you could use the
standard Sphinx citations, but it might be more practical to use the
After installing the sphinxcontrib.bibtex extension, you have to enable it in
conf.py and select the BibTeX file(s) you want to use:
extensions = [
# Probably more extensions here ...
bibtex_bibfiles = ['my-references.bib']
Afterwards all the references defined in the bibliography file(s) can be used
throughout the Jupyter notebooks and other source files as detailed in the following.
You can create citations like [PGH11]:
You can create similar citations in Jupyter notebooks with a special HTML
syntax, see the section about
citations in Markdown cells.
You can create a list of references in any reStructuredText file
(or reST cell in a notebook) like this:
Have a look at the documentation for all the available options.
The list of references may look something like this (in HTML output):
Thomas Kluyver, Benjamin Ragan-Kelley, Fernando Pérez, Brian Granger, Matthias Bussonnier, Jonathan Frederic, Kyle Kelley, Jessica Hamrick, Jason Grout, Sylvain Corlay, Paul Ivanov, Damián Avila, Safia Abdalla, Carol Willing, and Jupyter Development Team. Jupyter Notebooks—a publishing format for reproducible computational workflows. In Fernando Loizides and Birgit Schmidt, editors, Positioning and Power in Academic Publishing: Players, Agents and Agendas, pages 87–90. IOS Press, 2016. doi:10.3233/978-1-61499-649-1-87.
Fernando Pérez, Brian E. Granger, and John D. Hunter. Python: an ecosystem for scientific computing. Computing in Science Engineering, 13(2):13–21, 2011. doi:10.1109/MCSE.2010.119.