nbsphinx-link

What it is and what it does

nbsphinx-link solves the problem of including Jupyter notebooks in Sphinx documentation when those notebooks live outside the Sphinx source directory. Normally Sphinx restricts included files to the source tree, but this extension bridges that gap by letting you create lightweight .nblink JSON files that point to notebooks elsewhere on disk—useful for centralizing examples or shared notebook collections that multiple documentation projects reference.

The extension works by reading .nblink files (simple JSON with a "path" key pointing to a notebook and an optional "extra-media" array for associated images) and rendering the referenced notebook into your documentation build. It integrates directly into Sphinx's build pipeline and depends on nbsphinx to handle the actual notebook rendering.

Use it for:

• Include notebooks from a shared examples directory across multiple Sphinx documentation projects
• Reference notebooks stored in a separate repository or folder structure without copying them
• Build documentation that mixes RST files with external Jupyter notebooks using a single Sphinx config
• Manage notebook-based tutorials centrally while keeping documentation source trees lean

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Sphinx extension that lets you include Jupyter notebooks from directories outside your Sphinx source root by referencing them via .nblink JSON files.

Yes, if you use Sphinx and need to include Jupyter notebooks from outside your documentation source tree. Low install friction, active maintenance, permissive license, and no known vulnerabilities. The extension solves a specific but real Sphinx limitation with minimal overhead.

Install

nbsphinx-link on PyPI

pip install nbsphinx-link

uv add nbsphinx-link

poetry add nbsphinx-link

Installing nbsphinx-link

Before you install

Low friction install with active maintenance. Last release 77 days ago, repository not archived, and requires only nbsphinx and sphinx as dependencies.

License in practice

BSD-3-Clause permissive license allows use in most projects with minimal restrictions.

Quickstart

pip install nbsphinx-link

# In conf.py:
extensions = ['nbsphinx_link']

# Create example.nblink:
{"path": "../examples/notebook.ipynb"}

# Reference in RST:
.. include:: example.nblink

Requires Python 3.10 or later; nbsphinx and sphinx must be installed and configured.

Verify before relying

• Whether .nblink files support nested directory structures or only flat paths
• How media file paths are resolved when notebooks reference external assets
• Whether the extension handles notebook cell execution or only renders static output

Package facts

Evidence: nbsphinx_link-1.4.1-py3-none-any.whl

Keywords: Interactive, Interpreter, Shell, Web

Tags

More Sphinx packages