nbsphinx-link

1.3.1 verified Fri May 01 auth: no python maintenance

A Sphinx extension for including Jupyter notebook files that reside outside the Sphinx source root directory. Current version 1.3.1, supports Python 3+, released under BSD license. Releases are infrequent, last updated in 2021.

pip install nbsphinx-link

Common errors

error WARNING: unknown extension: nbsphinx-link ↓

cause Hyphen used instead of underscore in Sphinx extensions list

fix

Change 'nbsphinx-link' to 'nbsphinx_link' in conf.py extensions list.

error Error: Notebook file not found: /absolute/path/to/notebook.ipynb ↓

cause Trying to reference notebook with absolute path outside source directory without symlink

fix

Create a symlink from source directory to the notebook, or place notebook inside source root.

Warnings

breaking nbsphinx-link 1.0.0 changed the extension name from 'nbsphinx_link' (with underscore) to 'nbsphinx_link' (still underscore, but note: older docs sometimes used hyphen in configuration). Ensure you use underscore in Sphinx extensions list. ↓

fix Use 'nbsphinx_link' in extensions list, not 'nbsphinx-link'.

gotcha Notebooks must be placed relative to source directory or linked via symlinks. The extension does not handle absolute paths outside the source root automatically. ↓

fix Use symlinks or place notebooks in a subdirectory of your source root, or configure via nbsphinx_link_targets.

deprecated The extension is in maintenance mode; no new features. Sphinx 4+ compatibility is reported but not actively tested. ↓

fix Consider alternatives like 'jupyter-sphinx' or direct symlink management.

Imports

nbsphinx_link
wrong
```
extensions = ['nbsphinx-link']
```
correct
```
extensions = ['nbsphinx_link']
```
Use underscore not hyphen in Sphinx extensions list

Quickstart

Basic setup in Sphinx conf.py

# In conf.py
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
extensions = ['nbsphinx', 'nbsphinx_link']
# Create a symlink or use nbsphinx-link targets
# Example: create a symlink to an external notebook
# os.symlink('/path/to/external/notebook.ipynb', 'linked_notebook.ipynb')