Plugin for mkdocs to generate markdown documents from jupyter notebooks.
pip3 install mknotebooks
mknotebooksto the plugin section of your
- Include any notebooks (
.ipynbfiles) you want to use in the
docs/directory just as you would
# 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.
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.
# mkdocs.yml plugins: - mknotebooks execute: false timeout: 100 preamble: "<path/to/your/script>" allow_errors: false
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
In order to enable syntax highlighting for code blocks,
pygments has to be installed and
codehilite extension has to be enabled in
- Install pygments:
pip install Pygments
# mkdocs.yml markdown_extensions: - codehilite
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
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.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Hashes for mknotebooks-with-links-0.7.1.post0.dev806.tar.gz