Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/greenape/mknotebooks
A plugin for mkdocs to help you include Jupyter notebooks in your projects
https://github.com/greenape/mknotebooks
Last synced: 12 days ago
JSON representation
A plugin for mkdocs to help you include Jupyter notebooks in your projects
- Host: GitHub
- URL: https://github.com/greenape/mknotebooks
- Owner: greenape
- License: mit
- Created: 2018-09-18T08:13:25.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-08-11T11:59:54.000Z (over 1 year ago)
- Last Synced: 2024-05-14T05:02:55.160Z (6 months ago)
- Language: Python
- Size: 2.74 MB
- Stars: 127
- Watchers: 2
- Forks: 21
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- best-of-jupyter - GitHub - 35% open · ⏱️ 11.08.2023): (Notebook Sharing & Conversion)
README
# mknotebooks
mknotebooks is a plugin for [MkDocs](https://mkdocs.org) enabling you to include [Jupyter](https://jupyter.org) notebooks directly in your project documentation.
## Install
`pip3 install mknotebooks`
## Usage
- Add `mknotebooks` to the plugin section of your `mkdocs.yml`
- Include any notebooks (`.ipynb` files) you want to use in the `docs/` directory just as you would `.md` files.
Example:
```yaml
# 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: ""`. The default cell execution timeout can be overridden by setting `timeout: `, where `` 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:
```yaml
# mkdocs.yml
plugins:
- mknotebooks
execute: false
timeout: 100
preamble: ""
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`.
1. Install pygments:
```
pip install Pygments
```
2. Enable `codehilite` extension in `mkdocs.yml`:
```
# mkdocs.yml
markdown_extensions:
- codehilite
```
### Binder
You can also choose to have mknotebooks insert a [Binder](https://mybinder.org) link into each notebook.
``` mkdocs.yml
- 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](examples/) for examples on the [use of a preamble](examples/execute_with_preamble) and [using Binder](examples/binder_logo). 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.