<p align="center">
<img src="https://raw.githubusercontent.com/danielfrg/mkdocs-jupyter/main/docs/logo.png" width="450px">
</p>
<p align="center">
<a href="https://pypi.org/project/mkdocs-jupyter/">
<img src="https://img.shields.io/pypi/v/mkdocs-jupyter.svg">
</a>
<a href="https://pypi.org/project/mkdocs-jupyter/">
<img src="https://img.shields.io/pypi/pyversions/mkdocs-jupyter.svg">
</a>
<a href="https://github.com/danielfrg/mkdocs-jupyter/actions/workflows/test.yml">
<img src="https://github.com/danielfrg/mkdocs-jupyter/workflows/test/badge.svg">
</a>
<a href="https://codecov.io/gh/danielfrg/mkdocs-jupyter?branch=main">
<img src="https://codecov.io/gh/danielfrg/mkdocs-jupyter/branch/main/graph/badge.svg">
</a>
<a href="http://github.com/danielfrg/mkdocs-jupyter/blob/main/LICENSE.txt">
<img src="https://img.shields.io/:license-Apache%202-blue.svg">
</a>
</p>
# mkdocs-jupyter: Use Jupyter Notebooks in mkdocs
- [Docs demo Site](https://mkdocs-jupyter.danielfrg.com/)
- Add Jupyter Notebooks directly to the mkdocs navigation
- Support for multiple formats:
- `.ipynb` and `.py` files (using
[jupytext](https://github.com/mwouts/jupytext))
- Same style as regular Jupyter Notebooks
- Support Jupyter Themes
- Option to execute the notebook before converting
- Support for [ipywidgets](https://github.com/jupyter-widgets/ipywidgets)
- Support for mkdocs TOC
- Option to include notebook source
<a
href="https://raw.githubusercontent.com/danielfrg/mkdocs-jupyter/master/docs/mkdocs-theme.png"><img
src="https://raw.githubusercontent.com/danielfrg/mkdocs-jupyter/master/docs/mkdocs-theme.png"
alt="mkdocs-jupyter default theme" width="300"></a> <a
href="https://raw.githubusercontent.com/danielfrg/mkdocs-jupyter/master/docs/material-theme.png"><img
src="https://raw.githubusercontent.com/danielfrg/mkdocs-jupyter/master/docs/material-theme.png"
alt="mkdocs-jupyter material theme" width="300"></a>
## Installation
```shell
pip install mkdocs-jupyter
```
## Configuration
In the `mkdocs.yml` use Jupyter notebooks (`.ipynb`) or Python scripts (`.py`)
as pages:
```yaml
nav:
- Home: index.md
- Notebook page: notebook.ipynb
- Python file: python_script.py
plugins:
- mkdocs-jupyter
```
### Titles and Table of Contents
The first h1 header (`#`) in your notebook will be used as the title.
```md
# This H1 header will be the the title.
```
This can be turned off in the configuration (in which case the filename will be
used as title):
```yaml
plugins:
- mkdocs-jupyter:
ignore_h1_titles: True
```
In order to see the table of contents you need to maintain a hierarchical
headers structure in your notebooks. You must use h2 headers (`##`) and not h1
(`#`)
```md
## This H2 title will show in the table of contents
```
If you want to **nest headers** in the TOC you need to add additional levels
later in the same markdown cell or new bottom markdown cells:
```md
## This header will show as top level in the table of contents
<content>
### This one will be displayed inside the above level
```
### Including or Ignoring Files
You can control which files are included or ignored via lists of glob patterns:
```yaml
plugins:
- mkdocs-jupyter:
include: ["*.ipynb"] # Default: ["*.py", "*.ipynb"]
ignore: ["some-irrelevant-files/*.ipynb"]
```
### Execute Notebook
You can tell the plugin to execute the notebook before converting, default is
`False`:
```yaml
plugins:
- mkdocs-jupyter:
execute: true
```
You can tell the plugin to ignore the execution of some files (with glob
matching):
```yaml
plugins:
- mkdocs-jupyter:
execute_ignore:
- "my-secret-files/*.ipynb"
```
To fail when notebook execution fails set `allow_errors` to `false`:
```yaml
plugins:
- mkdocs-jupyter:
execute: true
allow_errors: false
```
#### Kernel
By default the plugin will use the kernel specified in the notebook to execute
it. You can specify a custom kernel name to use for all the notebooks:
```yaml
plugins:
- mkdocs-jupyter:
kernel_name: python3
```
### Ignore Code Input
By default the plugin will show full code and regular cell output details. You
can hide cell code input for all the notebooks:
```yaml
plugins:
- mkdocs-jupyter:
show_input: False
```
You can also decide to hide the `Out[#]` output notation and other cell metadata
for all the notebooks:
```yaml
plugins:
- mkdocs-jupyter:
no_input: True
```
### Remove Cell Using Tags
By default the plugin will show full code and regular cell output details. You
can hide cell code input for specific cells using tags:
```yaml
plugins:
- mkdocs-jupyter:
remove_tag_config:
remove_input_tags:
- hide_code
```
More detailed on removing cell based on tag, see [NbConvert
Customization](https://nbconvert.readthedocs.io/en/latest/removing_cells.html))
### Jupyter themes
You can configure the different Jupyter themes. For example if using material
with `slate` color scheme you can use the Jupyter Lab `dark` theme:
```yml
plugins:
- mkdocs-jupyter:
theme: dark
theme:
name: material
palette:
scheme: slate
```
### Extra CSS classes
This option will add a custom CSS class to the `div` container that highlights
the code cells. This can be useful to add custom styles to the code cells.
```yml
plugins:
- mkdocs-jupyter:
highlight_extra_classes: "custom-css-classes
```
### RequireJS
By default RequireJS is not loaded. This is required for Plotly.
You can enable it with:
```yml
plugins:
- mkdocs-jupyter:
include_requirejs: true
```
### Download notebook link
You can tell the plugin to include the notebook source to make it easy to show a
download button in the theme, default is `False`:
```yml
plugins:
- mkdocs-jupyter:
include_source: True
```
This setting will also create a `page.nb_url` value that you can use in your
theme to make a link in each page.
For example in `mkdocs-material` (see
[customization](https://squidfunk.github.io/mkdocs-material/customization/#overriding-template-blocks)),
you can create a `main.html` file like this:
```jinja
{% extends "base.html" %}
{% block content %}
{% if page.nb_url %}
<a href="{{ page.nb_url }}" title="Download Notebook" class="md-content__button md-icon">
{% include ".icons/material/download.svg" %}
</a>
{% endif %}
{{ super() }}
{% endblock content %}
```
## Styles
This extensions includes the Jupyter Lab nbconvert CSS styles and does some
modifications to make it as generic as possible in order for it to work with a
variety of mkdocs themes. This is not always possible and the theme we test the
most is [mkdocs-material](https://squidfunk.github.io/mkdocs-material).
It's possible you might need to do some CSS changes to make it look as good as
you want, for example for the material theme take a look at their [customization
docs](https://squidfunk.github.io/mkdocs-material/customization/#overriding-template-blocks).
Create a `main.html` file like:
```jinja
{% extends "base.html" %}
{% block content %}
{{ super() }}
<style>
// Do whatever changes you need here
.jp-RenderedHTMLCommon p {
color: red
}
</style>
{% endblock content %}
```
## Mkdocs Material notes
Any markdown specific features such as
[admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/)
won't work with mkdocs-jupyter because those features are not supported by
Jupyter itself and we use [nbconvert](https://nbconvert.readthedocs.io/) to make
the conversion.
To use this type of features you have to define the HTML directly in the
markdown cells:
```html
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>
If two distributions are similar, then their entropies are similar,
implies the KL divergence with respect to two distributions will be
smaller...
</p>
</div>
```
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-jupyter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "documentation, jupyter, jupyterlab, mkdocs, notebooks",
"author": null,
"author_email": "Daniel Rodriguez <daniel@danielfrg.com>",
"download_url": null,
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/danielfrg/mkdocs-jupyter/main/docs/logo.png\" width=\"450px\">\n</p>\n\n<p align=\"center\">\n <a href=\"https://pypi.org/project/mkdocs-jupyter/\">\n <img src=\"https://img.shields.io/pypi/v/mkdocs-jupyter.svg\">\n </a>\n <a href=\"https://pypi.org/project/mkdocs-jupyter/\">\n <img src=\"https://img.shields.io/pypi/pyversions/mkdocs-jupyter.svg\">\n </a>\n <a href=\"https://github.com/danielfrg/mkdocs-jupyter/actions/workflows/test.yml\">\n <img src=\"https://github.com/danielfrg/mkdocs-jupyter/workflows/test/badge.svg\">\n </a>\n <a href=\"https://codecov.io/gh/danielfrg/mkdocs-jupyter?branch=main\">\n <img src=\"https://codecov.io/gh/danielfrg/mkdocs-jupyter/branch/main/graph/badge.svg\">\n </a>\n <a href=\"http://github.com/danielfrg/mkdocs-jupyter/blob/main/LICENSE.txt\">\n <img src=\"https://img.shields.io/:license-Apache%202-blue.svg\">\n </a>\n</p>\n\n# mkdocs-jupyter: Use Jupyter Notebooks in mkdocs\n\n- [Docs demo Site](https://mkdocs-jupyter.danielfrg.com/)\n- Add Jupyter Notebooks directly to the mkdocs navigation\n- Support for multiple formats:\n - `.ipynb` and `.py` files (using\n [jupytext](https://github.com/mwouts/jupytext))\n- Same style as regular Jupyter Notebooks\n - Support Jupyter Themes\n- Option to execute the notebook before converting\n- Support for [ipywidgets](https://github.com/jupyter-widgets/ipywidgets)\n- Support for mkdocs TOC\n- Option to include notebook source\n\n<a\nhref=\"https://raw.githubusercontent.com/danielfrg/mkdocs-jupyter/master/docs/mkdocs-theme.png\"><img\nsrc=\"https://raw.githubusercontent.com/danielfrg/mkdocs-jupyter/master/docs/mkdocs-theme.png\"\nalt=\"mkdocs-jupyter default theme\" width=\"300\"></a> <a\nhref=\"https://raw.githubusercontent.com/danielfrg/mkdocs-jupyter/master/docs/material-theme.png\"><img\nsrc=\"https://raw.githubusercontent.com/danielfrg/mkdocs-jupyter/master/docs/material-theme.png\"\nalt=\"mkdocs-jupyter material theme\" width=\"300\"></a>\n\n## Installation\n\n```shell\npip install mkdocs-jupyter\n```\n\n## Configuration\n\nIn the `mkdocs.yml` use Jupyter notebooks (`.ipynb`) or Python scripts (`.py`)\nas pages:\n\n```yaml\nnav:\n - Home: index.md\n - Notebook page: notebook.ipynb\n - Python file: python_script.py\nplugins:\n - mkdocs-jupyter\n```\n\n### Titles and Table of Contents\n\nThe first h1 header (`#`) in your notebook will be used as the title.\n\n```md\n# This H1 header will be the the title.\n```\n\nThis can be turned off in the configuration (in which case the filename will be\nused as title):\n\n```yaml\nplugins:\n - mkdocs-jupyter:\n ignore_h1_titles: True\n```\n\nIn order to see the table of contents you need to maintain a hierarchical\nheaders structure in your notebooks. You must use h2 headers (`##`) and not h1\n(`#`)\n\n```md\n## This H2 title will show in the table of contents\n```\n\nIf you want to **nest headers** in the TOC you need to add additional levels\nlater in the same markdown cell or new bottom markdown cells:\n\n```md\n## This header will show as top level in the table of contents\n\n<content>\n\n### This one will be displayed inside the above level\n```\n\n### Including or Ignoring Files\n\nYou can control which files are included or ignored via lists of glob patterns:\n\n```yaml\nplugins:\n - mkdocs-jupyter:\n include: [\"*.ipynb\"] # Default: [\"*.py\", \"*.ipynb\"]\n ignore: [\"some-irrelevant-files/*.ipynb\"]\n```\n\n### Execute Notebook\n\nYou can tell the plugin to execute the notebook before converting, default is\n`False`:\n\n```yaml\nplugins:\n - mkdocs-jupyter:\n execute: true\n```\n\nYou can tell the plugin to ignore the execution of some files (with glob\nmatching):\n\n```yaml\nplugins:\n - mkdocs-jupyter:\n execute_ignore:\n - \"my-secret-files/*.ipynb\"\n```\n\nTo fail when notebook execution fails set `allow_errors` to `false`:\n\n```yaml\nplugins:\n - mkdocs-jupyter:\n execute: true\n allow_errors: false\n```\n\n#### Kernel\n\nBy default the plugin will use the kernel specified in the notebook to execute\nit. You can specify a custom kernel name to use for all the notebooks:\n\n```yaml\nplugins:\n - mkdocs-jupyter:\n kernel_name: python3\n```\n\n### Ignore Code Input\n\nBy default the plugin will show full code and regular cell output details. You\ncan hide cell code input for all the notebooks:\n\n```yaml\nplugins:\n - mkdocs-jupyter:\n show_input: False\n```\n\nYou can also decide to hide the `Out[#]` output notation and other cell metadata\nfor all the notebooks:\n\n```yaml\nplugins:\n - mkdocs-jupyter:\n no_input: True\n```\n\n### Remove Cell Using Tags\n\nBy default the plugin will show full code and regular cell output details. You\ncan hide cell code input for specific cells using tags:\n\n```yaml\nplugins:\n - mkdocs-jupyter:\n remove_tag_config:\n remove_input_tags:\n - hide_code\n```\n\nMore detailed on removing cell based on tag, see [NbConvert\nCustomization](https://nbconvert.readthedocs.io/en/latest/removing_cells.html))\n\n### Jupyter themes\n\nYou can configure the different Jupyter themes. For example if using material\nwith `slate` color scheme you can use the Jupyter Lab `dark` theme:\n\n```yml\nplugins:\n - mkdocs-jupyter:\n theme: dark\n\ntheme:\n name: material\n palette:\n scheme: slate\n```\n\n### Extra CSS classes\n\nThis option will add a custom CSS class to the `div` container that highlights\nthe code cells. This can be useful to add custom styles to the code cells.\n\n```yml\nplugins:\n - mkdocs-jupyter:\n highlight_extra_classes: \"custom-css-classes\n```\n\n### RequireJS\n\nBy default RequireJS is not loaded. This is required for Plotly.\nYou can enable it with:\n\n```yml\nplugins:\n - mkdocs-jupyter:\n include_requirejs: true\n```\n\n### Download notebook link\n\nYou can tell the plugin to include the notebook source to make it easy to show a\ndownload button in the theme, default is `False`:\n\n```yml\nplugins:\n - mkdocs-jupyter:\n include_source: True\n```\n\nThis setting will also create a `page.nb_url` value that you can use in your\ntheme to make a link in each page.\n\nFor example in `mkdocs-material` (see\n[customization](https://squidfunk.github.io/mkdocs-material/customization/#overriding-template-blocks)),\nyou can create a `main.html` file like this:\n\n```jinja\n{% extends \"base.html\" %}\n\n{% block content %}\n{% if page.nb_url %}\n <a href=\"{{ page.nb_url }}\" title=\"Download Notebook\" class=\"md-content__button md-icon\">\n {% include \".icons/material/download.svg\" %}\n </a>\n{% endif %}\n\n{{ super() }}\n{% endblock content %}\n```\n\n\n\n## Styles\n\nThis extensions includes the Jupyter Lab nbconvert CSS styles and does some\nmodifications to make it as generic as possible in order for it to work with a\nvariety of mkdocs themes. This is not always possible and the theme we test the\nmost is [mkdocs-material](https://squidfunk.github.io/mkdocs-material).\n\nIt's possible you might need to do some CSS changes to make it look as good as\nyou want, for example for the material theme take a look at their [customization\ndocs](https://squidfunk.github.io/mkdocs-material/customization/#overriding-template-blocks).\n\nCreate a `main.html` file like:\n\n```jinja\n{% extends \"base.html\" %}\n\n{% block content %}\n{{ super() }}\n\n<style>\n// Do whatever changes you need here\n\n.jp-RenderedHTMLCommon p {\n color: red\n}\n\n</style>\n{% endblock content %}\n```\n\n## Mkdocs Material notes\n\nAny markdown specific features such as\n[admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/)\nwon't work with mkdocs-jupyter because those features are not supported by\nJupyter itself and we use [nbconvert](https://nbconvert.readthedocs.io/) to make\nthe conversion.\n\nTo use this type of features you have to define the HTML directly in the\nmarkdown cells:\n\n```html\n<div class=\"admonition note\">\n <p class=\"admonition-title\">Note</p>\n <p>\n If two distributions are similar, then their entropies are similar,\n implies the KL divergence with respect to two distributions will be\n smaller...\n </p>\n</div>\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Use Jupyter in mkdocs websites",
"version": "0.24.7",
"project_urls": {
"Documentation": "https://github.com/danielfrg/mkdocs-jupyter#readme",
"Issues": "https://github.com/danielfrg/mkdocs-jupyter/issues",
"Source": "https://github.com/danielfrg/mkdocs-jupyter"
},
"split_keywords": [
"documentation",
" jupyter",
" jupyterlab",
" mkdocs",
" notebooks"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "62f8983211642f506bccab6f85473e75f031e51f55b97f23e6f910839916a657",
"md5": "01c1d8991b8050dea28c9e251baeef11",
"sha256": "893d04bea1e007479a46e4e72852cd4d280c4d358ce4a0445250f3f80c639723"
},
"downloads": -1,
"filename": "mkdocs_jupyter-0.24.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "01c1d8991b8050dea28c9e251baeef11",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 1442736,
"upload_time": "2024-04-09T02:28:35",
"upload_time_iso_8601": "2024-04-09T02:28:35.981999Z",
"url": "https://files.pythonhosted.org/packages/62/f8/983211642f506bccab6f85473e75f031e51f55b97f23e6f910839916a657/mkdocs_jupyter-0.24.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-09 02:28:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "danielfrg",
"github_project": "mkdocs-jupyter#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-jupyter"
}
JSON
