# mkdocs-nbconvert
[](https://pypi.org/project/mkdocs-nbconvert/)
[](https://github.com/tanbro/mkdocs-nbconvert)
[](https://github.com/tanbro/mkdocs-nbconvert/actions/workflows/workflow.yml)
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](http://www.mkdocs.org/) plugin is based on [Jupyter](https://jupyter.org/) [nbconvert](https://nbconvert.readthedocs.io/).
When install the plugin, jupyter and nbconvert will also be installed.
### Install by pip
```sh
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
```yaml
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`:
```yaml
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` files
Either 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`](https://www.mkdocs.org/user-guide/configuration/#docs_dir)
When omitted, default value is `notebooks`.
- `recursive`: Whether scan `*.ipynb` files in subdirectories recursively
When 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 take `input_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 is `true`.
Options can be add to configuration file as below:
```yaml
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`](https://www.mkdocs.org/user-guide/configuration/#docs_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
- <https://tanbro.github.io/mkdocs-nbconvert/>
- <https://www.mkdocs.org/user-guide/plugins/>
## 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:
```bash
pip install -e . --group docs
mkdocs serve
```
[MkDocs]: http://www.mkdocs.org/
[Jupyter]: https://jupyter.org/
[nbconvert]: https://pypi.org/project/nbconvert/
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-nbconvert",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mkdocs, mkdocs-plugin, jupyter, notebook, jupyter-notebook, markdown, md, nbconvert",
"author": null,
"author_email": "liu xue yan <liu_xue_yan@foxmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f2/6f/483c5ceac39e4a6915d7674919030b4d8d33078e083a4a6a441b76374055/mkdocs_nbconvert-0.5.tar.gz",
"platform": null,
"description": "# mkdocs-nbconvert\r\n\r\n[](https://pypi.org/project/mkdocs-nbconvert/)\r\n[](https://github.com/tanbro/mkdocs-nbconvert)\r\n[](https://github.com/tanbro/mkdocs-nbconvert/actions/workflows/workflow.yml)\r\n\r\nA [MkDocs][] plugin provides a source parser for `*.ipynb` [Jupyter][] Notebook files, based on [nbconvert][].\r\n\r\n## Features\r\n\r\n- Converts Jupyter Notebook files (`.ipynb`) to Markdown during the MkDocs build process\r\n- Supports executing notebooks before conversion to include output results\r\n- Concurrent processing for faster builds with `max_workers` option\r\n- Flexible configuration for input/output directories and execution options\r\n- Automatic cleanup of temporary files after build\r\n\r\n## Installation\r\n\r\nThis [MkDocs](http://www.mkdocs.org/) plugin is based on [Jupyter](https://jupyter.org/) [nbconvert](https://nbconvert.readthedocs.io/).\r\n\r\nWhen install the plugin, jupyter and nbconvert will also be installed.\r\n\r\n### Install by pip\r\n\r\n```sh\r\npip install mkdocs-nbconvert\r\n```\r\n\r\n### Install from source\r\n\r\n```\r\ngit clone https://github.com/tanbro/mkdocs-nbconvert.git\r\ncd mkdocs-nbconvert\r\npip install .\r\n```\r\n\r\n## Quick Start\r\n\r\n### Mkdocs configuration\r\n\r\nAdd the `nbconvert` into configuration file (`mkdocs.yml`)'s `plugins` list\r\n\r\n```yaml\r\nplugins:\r\n - nbconvert\r\n```\r\n\r\nIn `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`:\r\n\r\n```yaml\r\nnav:\r\n - index.md\r\n - Notebooks:\r\n - notebooks/installation.md\r\n - notebooks/usage.md\r\n - notebooks/image.md\r\n - notebooks/matplotlib.md\r\n - authors.md\r\n - changelog.md\r\n```\r\n\r\n> **Warning:**\r\n>\r\n> converted `notebooks/*.md` files will be removed at the end of building.\r\n\r\n## Configuration\r\n\r\nThe plugin provides several configuration options:\r\n\r\n- `input_dir`: Directory where to scan `*.ipynb` files\r\n\r\n Either absolute or relative path.\r\n When relative, it's from `mkdocs` configuration file's directory.\r\n\r\n When omitted, default value is `notebooks`\r\n\r\n- `output_dir`: Export notebook files to markdown files in the directory.\r\n\r\n It **MUST** be a **relative** path to [`doc_dir`](https://www.mkdocs.org/user-guide/configuration/#docs_dir)\r\n\r\n When omitted, default value is `notebooks`.\r\n\r\n- `recursive`: Whether scan `*.ipynb` files in subdirectories recursively\r\n\r\n When omitted, default value is `True`\r\n\r\n- `execute_enabled`: Whether executing notebooks before convert. `false` by default\r\n\r\n- `max_workers`: Number of concurrent threads used to process notebooks. Defaults to the number of CPU cores.\r\n\r\n- `execute_options`: Options for execution:\r\n\r\n - `execute_options.run_path`: Specifies in which folder to execute the notebook. The plugin in will take `input_dir` as the path if not specified.\r\n\r\n - `execute_options.kernel_name`: The execution kernel. When not specified, the default Python kernel is chosen.\r\n\r\n - `execute_options.timeout`: The cell execution timeout. No timeout when not specified.\r\n\r\n - `execute_options.write_back`: Whether save executed result to the notebook file. `false` by default.\r\n\r\n - `execute_options.exit_on_error`: Whether exit when an error occurred. Default is `true`.\r\n\r\nOptions can be add to configuration file as below:\r\n\r\n```yaml\r\nplugins:\r\n - nbconvert:\r\n input_dir: notebooks\r\n recursive: true\r\n output_dir: notebooks\r\n execute_enabled: true\r\n max_workers: 4\r\n execute_options:\r\n write_back: true\r\n exit_on_error: true\r\n```\r\n\r\nIn 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`](https://www.mkdocs.org/user-guide/configuration/#docs_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.\r\n\r\n## References\r\n\r\n- <https://tanbro.github.io/mkdocs-nbconvert/>\r\n- <https://www.mkdocs.org/user-guide/plugins/>\r\n\r\n## Build the Site\r\n\r\nThe project's documentation site serves as a demo of how to use it.\r\n\r\nTo build and serve the doc-site, run the following command in on a virtual environment:\r\n\r\n```bash\r\npip install -e . --group docs\r\nmkdocs serve\r\n```\r\n\r\n[MkDocs]: http://www.mkdocs.org/\r\n[Jupyter]: https://jupyter.org/\r\n[nbconvert]: https://pypi.org/project/nbconvert/\r\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "A MkDocs plug-in provides a source parser for *.ipynb Jupyter notebook files, base on nbconvert.",
"version": "0.5",
"project_urls": {
"Documentation": "https://tanbro.github.io/mkdocs-nbconvert",
"Homepage": "https://tanbro.github.io/mkdocs-nbconvert",
"Repository": "https://github.com/tanbro/mkdocs-nbconvert"
},
"split_keywords": [
"mkdocs",
" mkdocs-plugin",
" jupyter",
" notebook",
" jupyter-notebook",
" markdown",
" md",
" nbconvert"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0ab2d70a541be48bf777aba68541c4ad7b732e979b53cef3e24bfd80a33d78c3",
"md5": "84bd6111439604e5751d7d9a259c7300",
"sha256": "2a64c4f4aa6fbbe58f3b1eb6a74835c2376b5bf8c6e651da4f822bc09190453c"
},
"downloads": -1,
"filename": "mkdocs_nbconvert-0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "84bd6111439604e5751d7d9a259c7300",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8513,
"upload_time": "2025-10-10T13:52:12",
"upload_time_iso_8601": "2025-10-10T13:52:12.854822Z",
"url": "https://files.pythonhosted.org/packages/0a/b2/d70a541be48bf777aba68541c4ad7b732e979b53cef3e24bfd80a33d78c3/mkdocs_nbconvert-0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f26f483c5ceac39e4a6915d7674919030b4d8d33078e083a4a6a441b76374055",
"md5": "d6d509b01ec3ee0d33b22829ef6aadf8",
"sha256": "d1f7f6bdd701f9aa1a6a80e569e3391eed8074697097776aebd1d4311caa3c90"
},
"downloads": -1,
"filename": "mkdocs_nbconvert-0.5.tar.gz",
"has_sig": false,
"md5_digest": "d6d509b01ec3ee0d33b22829ef6aadf8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13474,
"upload_time": "2025-10-10T13:52:14",
"upload_time_iso_8601": "2025-10-10T13:52:14.385056Z",
"url": "https://files.pythonhosted.org/packages/f2/6f/483c5ceac39e4a6915d7674919030b4d8d33078e083a4a6a441b76374055/mkdocs_nbconvert-0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-10 13:52:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tanbro",
"github_project": "mkdocs-nbconvert",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-nbconvert"
}
JSON
