Plugin for mkdocs to generate markdown documents from jupyter notebooks.
Project description
mknotebooks
mknotebooks is a plugin for MkDocs enabling you to include Jupyter notebooks directly in your project documentation.
Install
pip3 install mknotebooks
Usage
- Add
mknotebooks
to the plugin section of yourmkdocs.yml
- Include any notebooks (
.ipynb
files) you want to use in thedocs/
directory just as you would.md
files.
Example:
# mkdocs.yml
nav:
- your_notebook.ipynb
plugins:
- mknotebooks
Any static images, plots, etc. will be extracted from the notebook and placed alongside the output HTML.
Options
You can optionally execute the notebooks, by setting execute: true
in the config. You can include a hidden preamble script, to be run before executing any cells using preamble: "<path/to/your/script>"
. The default cell execution timeout can be overridden by setting timeout: <timeout>
, where <timeout>
is an integer number of seconds.
By default, execution will be aborted if any of the cells throws an error, but you can set allow_errors: true
to continue execution and include the error message in the cell output.
Example:
# mkdocs.yml
plugins:
- mknotebooks
execute: false
timeout: 100
preamble: "<path/to/your/script>"
allow_errors: false
Styling
Mknotebooks applies default styling to improve the appearance of notebook input/output cells and pandas dataframes. If these interfere with any other CSS stylesheets that you're using, you can disable these via the following options.
# mkdocs.yml
- mknotebooks:
enable_default_jupyter_cell_styling: false
enable_default_pandas_dataframe_styling: false
Syntax highlighting
In order to enable syntax highlighting for code blocks, pygments
has to be installed and codehilite
extension has to be enabled in mkdocs.yml
.
- Install pygments:
pip install Pygments
- Enable
codehilite
extension inmkdocs.yml
:
# mkdocs.yml
markdown_extensions:
- codehilite
Binder
You can also choose to have mknotebooks insert a Binder link into each notebook.
- mknotebooks:
binder: true
binder_service_name: "gh"
binder_branch: "master"
binder_ui: "lab"
If you are using GitLab, you will need to set binder_service_name
to "gl"
.
Examples
See the examples folder for examples on the use of a preamble and using Binder. Try them out by running pipenv install && pipenv run mkdocs serve
.
Inspecting generated markdown
You can also export the generated markdown by setting write_markdown: true
in your mkdocs.yml
. This will write the generated markdown to a .md.tmp
file alongside the original notebook.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for mknotebooks_with_links-0.7.1.post0.dev809-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4022b02c28b36f060e546a1f5be5d95b85f7549e52d49753fb92ae1bbdc5aad8 |
|
MD5 | fe13f37353054c5c30aa91287176e1c7 |
|
BLAKE2b-256 | 8f540ac6d7a48aef1f357ff846c6139aeceede4e9c390289eb6655518b029124 |