Skip to main content

No project description provided

Project description

mkdocs-jupyter: Use Jupyter Notebooks in mkdocs

PyPI Testing Coverage Status License

  • Add Jupyter Notebooks directly to the mkdocs navigation
  • Support for multiple formats:
  • Same style as regular Jupyter Notebooks
  • Option to execute the notebook before converting
  • Support for ipywidgets
  • Support for mkdocs TOC
  • Option to include notebook source

mkdocs-jupyter default theme mkdocs-jupyter material theme

Usage

pip install mkdocs-jupyter

In your mkdocs.yml:

nav:
- Home: index.md
- Notebook page: notebook.ipynb
- Python file: python_script.py

plugins:
  - mkdocs-jupyter

Options

Execute Notebook

You can tell the plugin to execute the notebook before converting, default is False:

plugins:
  - mkdocs-jupyter:
      execute: True

Kernel Name

By default the plugin will use the kernel specified in the notebook to execute it. You can specify a custom kernel name to use for all the notebooks:

plugins:
  - mkdocs-jupyter:
      kernel_name: python3

Download notebook link

You can tell the plugin to include the notebook source to make it easy to show a download button in the theme, default is False:

plugins:
  - mkdocs-jupyter:
      include_source: True

This setting will also create a page.nb_url value that you can use in your theme to make a link in each page.

For example in mkdocs-material (see customization), you can create a main.html file like this:

{% extends "base.html" %}

{% block content %}
{% if page.nb_url %}
    <a href="{{ page.nb_url }}" title="Download Notebook" class="md-content__button md-icon">
        {% include ".icons/material/download.svg" %}
    </a>
{% endif %}

{{ super() }}
{% endblock content %}

Download Noteboon button

Styles

This extensions includes some CSS styles to make the Notebook look "decent" inside a generic mkdoc theme but in general some extra customization needs to be done to make the Jupyter Notebook based pages look as good and native as the markdown ones. This is usually simple CSS tweaks.

Material theme

For popular the mkdocs-material please take a look at their customization docs)

Create a main.html file like:

{% extends "base.html" %}

{% block content %}
{{ super() }}

<style>
    .jp-RenderedHTMLCommon p {
        font-size: .8rem;
        line-height: 1.6;
    }

    .jp-RenderedHTMLCommon li {
        font-size: .8rem;
        line-height: 1.6;
    }

    .jp-RenderedHTMLCommon h1 {
        margin: 0 0 1.25em;
        color: var(--md-default-fg-color--light);
        font-weight: 300;
        font-size: 2em;
        line-height: 1.3;
        letter-spacing: -0.01em;
    }

    .jp-RenderedHTMLCommon h2 {
        margin: 1.6em 0 .64em;
        font-weight: 300;
        font-size: 1.965em;
        line-height: 1.4;
        letter-spacing: -0.01em;
    }

    .jp-RenderedHTMLCommon h3 {
        margin: 1.6em 0 .8em;
        font-weight: 400;
        font-size: 1.57em;
        line-height: 1.5;
        letter-spacing: -0.01em;
    }

    .jp-RenderedHTMLCommon hr {
        border: none;
    }
</style>
{% endblock content %}

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for mkdocs-jupyter, version 0.16.1
Filename, size File type Python version Upload date Hashes
Filename, size mkdocs-jupyter-0.16.1.tar.gz (1.7 MB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page