# 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: "<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:
```yaml
# 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`.
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.
Raw data
{
"_id": null,
"home_page": "https://github.com/greenape/mknotebooks",
"name": "mknotebooks",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "mkdocs documentation markdown",
"author": "Jonathan Gray",
"author_email": "jonathan.gray@nanosheep.net",
"download_url": "",
"platform": "MacOS X",
"description": "\n\n\n\n\n\n# mknotebooks\n\nmknotebooks is a plugin for [MkDocs](https://mkdocs.org) enabling you to include [Jupyter](https://jupyter.org) notebooks directly in your project documentation.\n\n## Install\n\n`pip3 install mknotebooks`\n\n## Usage\n\n- Add `mknotebooks` to the plugin section of your `mkdocs.yml`\n- Include any notebooks (`.ipynb` files) you want to use in the `docs/` directory just as you would `.md` files.\n\nExample:\n\n```yaml\n# mkdocs.yml\nnav:\n - your_notebook.ipynb\n\nplugins:\n - mknotebooks\n```\n\nAny static images, plots, etc. will be extracted from the notebook and placed alongside the output HTML.\n\n### Options\n\nYou 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.\n\nBy 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.\n\nExample:\n\n\n```yaml\n# mkdocs.yml\nplugins:\n - mknotebooks\n execute: false\n timeout: 100\n preamble: \"<path/to/your/script>\"\n allow_errors: false\n```\n\n### Styling\n\nMknotebooks 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.\n\n```\n# mkdocs.yml\n- mknotebooks:\n enable_default_jupyter_cell_styling: false\n enable_default_pandas_dataframe_styling: false\n```\n\n### Syntax highlighting\n\nIn order to enable syntax highlighting for code blocks, `pygments` has to be installed and `codehilite` extension has to be enabled in `mkdocs.yml`.\n\n1. Install pygments:\n\n```\npip install Pygments\n```\n\n2. Enable `codehilite` extension in `mkdocs.yml`:\n\n```\n# mkdocs.yml\nmarkdown_extensions:\n - codehilite\n```\n\n### Binder\n\nYou can also choose to have mknotebooks insert a [Binder](https://mybinder.org) link into each notebook.\n\n``` mkdocs.yml\n- mknotebooks:\n binder: true\n binder_service_name: \"gh\"\n binder_branch: \"master\"\n binder_ui: \"lab\"\n```\n\nIf you are using GitLab, you will need to set `binder_service_name` to `\"gl\"`.\n\n## Examples\n\nSee 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`.\n\n## Inspecting generated markdown\n\nYou 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.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Plugin for mkdocs to generate markdown documents from jupyter notebooks.",
"version": "0.8.0",
"project_urls": {
"Homepage": "https://github.com/greenape/mknotebooks"
},
"split_keywords": [
"mkdocs",
"documentation",
"markdown"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "54402f69d9858c06d3fd9232fe7ead0c828cc3d64783edb98476782a7f125977",
"md5": "9da6de3be8a3b84df251a24e53d017ee",
"sha256": "4a9b998260c09bcc311455a19a44cc395a30ee82dc1e86e3316dd09f2445ebd3"
},
"downloads": -1,
"filename": "mknotebooks-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9da6de3be8a3b84df251a24e53d017ee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 13230,
"upload_time": "2023-08-07T10:01:06",
"upload_time_iso_8601": "2023-08-07T10:01:06.289811Z",
"url": "https://files.pythonhosted.org/packages/54/40/2f69d9858c06d3fd9232fe7ead0c828cc3d64783edb98476782a7f125977/mknotebooks-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-07 10:01:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "greenape",
"github_project": "mknotebooks",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"circle": true,
"lcname": "mknotebooks"
}
JSON
