This release is a pre-release and may not be stable for production use.
mknotebooks
mknotebooks is a plugin for MkDocs enabling you to include Jupyter notebooks directly in your project documentation.
Install
pip3 install mknotebooks
Usage
- Add
mknotebooksto the plugin section of yourmkdocs.yml - Include any notebooks (
.ipynbfiles) you want to use in thedocs/directory just as you would.mdfiles.
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
codehiliteextension 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.
1 maintainer
Metadata
1 maintainer
Release files for mknotebooks 0.7.1.post0.dev375
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mknotebooks-0.7.1.post0.dev375-py3-none-any.whl | Python 3 | none | any | Details |
Release files / mknotebooks-0.7.1.post0.dev375-py3-none-any.whl
| Download URL | mknotebooks-0.7.1.post0.dev375-py3-none-any.whl |
|---|---|
| Size | 13.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dfce62c273a7e1deff1d6c97c879b644d0e18415d56ab71634b738bdf19dda7b
|
|
BLAKE2b-256 checksum How to use checksums |
b2c4bd52d9593474480fbe56b8c4f5e1042aeb9481d21f0ab2c8ba37012389fe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.8.0 pkginfo/1.8.2 readme-renderer/32.0 requests/2.26.0 requests-toolbelt/0.9.1 urllib3/1.26.7 tqdm/4.62.3 importlib-metadata/4.11.0 keyring/21.8.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.7.12
|
