mkdocs-nbconvert¶
A MkDocs plugin provides a source parser for *.ipynb
Jupyter Notebook files, based on nbconvert.
Features¶
- Converts Jupyter Notebook files (
.ipynb
) to Markdown during the MkDocs build process - Supports executing notebooks before conversion to include output results
- Concurrent processing for faster builds with
max_workers
option - Flexible configuration for input/output directories and execution options
- Automatic cleanup of temporary files after build
Installation¶
This MkDocs plugin is based on Jupyter nbconvert.
When install the plugin, jupyter and nbconvert will also be installed.
Install by pip¶
pip install mkdocs-nbconvert
Install from source¶
git clone https://github.com/tanbro/mkdocs-nbconvert.git
cd mkdocs-nbconvert
pip install .
Quick Start¶
Mkdocs configuration¶
Add the nbconvert
into configuration file (mkdocs.yml
)'s plugins
list
plugins:
- nbconvert
In nav
section, add *.ipynb
files as normal markdown files with replacing extension *.ipynb
to *.md
, since they're converted to markdown files in output_dir
:
nav:
- index.md
- Notebooks:
- notebooks/installation.md
- notebooks/usage.md
- notebooks/image.md
- notebooks/matplotlib.md
- authors.md
- changelog.md
Warning:
converted
notebooks/*.md
files will be removed at the end of building.
Configuration¶
The plugin provides several configuration options:
-
input_dir
: Directory where to scan*.ipynb
filesEither absolute or relative path. When relative, it's from
mkdocs
configuration file's directory.When omitted, default value is
notebooks
-
output_dir
: Export notebook files to markdown files in the directory.It MUST be a relative path to
doc_dir
When omitted, default value is
notebooks
. -
recursive
: Whether scan*.ipynb
files in subdirectories recursivelyWhen omitted, default value is
True
-
execute_enabled
: Whether executing notebooks before convert.false
by default -
max_workers
: Number of concurrent threads used to process notebooks. Defaults to the number of CPU cores. -
execute_options
: Options for execution:-
execute_options.run_path
: Specifies in which folder to execute the notebook. The plugin in will takeinput_dir
as the path if not specified. -
execute_options.kernel_name
: The execution kernel. When not specified, the default Python kernel is chosen. -
execute_options.timeout
: The cell execution timeout. No timeout when not specified. -
execute_options.write_back
: Whether save executed result to the notebook file.false
by default. -
execute_options.exit_on_error
: Whether exit when an error occurred. Default istrue
.
-
Options can be add to configuration file as below:
plugins:
- nbconvert:
input_dir: notebooks
recursive: true
output_dir: notebooks
execute_enabled: true
max_workers: 4
execute_options:
write_back: true
exit_on_error: true
In the above example, the plugin recursively searches Jupyter notebook files in {{project_dir}}\notebooks
, then converts them to markdown files to {{project_dir}}\docs\notebooks
, where {{project_dir}}\docs
is the default value of doc_dir
configure. A pre-execution will be performed, and the running result will be saved to original notebook files. The conversion will be processed using 4 concurrent threads.
References¶
Build the Site¶
The project's documentation site serves as a demo of how to use it.
To build and serve the doc-site, run the following command in on a virtual environment:
pip install -e . --group docs
mkdocs serve