mkdocs-jupyter: 在mkdocs中使用Jupyter笔记本

• 文档演示网站
• 直接将Jupyter笔记本添加到mkdocs导航中
• 支持多种格式
  • .ipynb 和 .py 文件（使用 jupytext）
• 与常规Jupyter笔记本相同的样式
  • 支持Jupyter主题
• 在转换前执行笔记本的选项
• 支持 ipywidgets
• 支持mkdocs目录
• 包括笔记本源代码的选项

安装

pip install mkdocs-jupyter

配置

在 mkdocs.yml 中使用Jupyter笔记本（.ipynb）或Python脚本（.py）作为页面

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

标题和目录

您的笔记本中的第一个h1标题（#）将被用作标题。

# This H1 header will be the the title.

可以在配置中关闭此功能（在这种情况下，将使用文件名作为标题）

plugins:
    - mkdocs-jupyter:
          ignore_h1_titles: True

为了查看目录，您需要在笔记本中维护层次结构的标题结构。您必须使用h2标题（##），而不是h1（#）

## This H2 title will show in the table of contents

如果您想在目录中 嵌套标题，您需要在同一Markdown单元格中或新的底部Markdown单元格中添加额外的级别

## This header will show as top level in the table of contents

<content>

### This one will be displayed inside the above level

包括或忽略文件

您可以通过glob模式列表来控制哪些文件被包括或忽略

plugins:
    - mkdocs-jupyter:
          include: ["*.ipynb"] # Default: ["*.py", "*.ipynb"]
          ignore: ["some-irrelevant-files/*.ipynb"]

执行笔记本

您可以让插件在转换之前执行笔记本，默认为False

plugins:
    - mkdocs-jupyter:
          execute: true

您可以让插件忽略一些文件的执行（使用glob匹配）

plugins:
    - mkdocs-jupyter:
          execute_ignore:
              - "my-secret-files/*.ipynb"

当笔记本执行失败时，设置allow_errors为false以失败

plugins:
    - mkdocs-jupyter:
          execute: true
          allow_errors: false

内核

默认情况下，插件将使用笔记本中指定的内核来执行它。您可以指定一个用于所有笔记本的自定义内核名称

plugins:
    - mkdocs-jupyter:
          kernel_name: python3

忽略代码输入

默认情况下，插件将显示完整代码和常规单元格输出详细信息。您可以隐藏所有笔记本的单元格代码输入

plugins:
    - mkdocs-jupyter:
          show_input: False

您还可以决定隐藏所有笔记本的Out[#]输出符号和其他单元格元数据

plugins:
    - mkdocs-jupyter:
          no_input: True

使用标签删除单元格

默认情况下，插件将显示完整代码和常规单元格输出详细信息。您可以使用标签隐藏特定单元格的代码输入

plugins:
    - mkdocs-jupyter:
          remove_tag_config:
              remove_input_tags:
                  - hide_code

有关基于标签删除单元格的更多详细说明，请参阅NbConvert 自定义)

Jupyter 主题

您可以为不同的 Jupyter 主题进行配置。例如，如果您使用带有slate颜色方案的 material，您可以使用 Jupyter Lab 的dark主题

plugins:
    - mkdocs-jupyter:
          theme: dark

theme:
    name: material
    palette:
        scheme: slate

额外 CSS 类

此选项将向div容器添加自定义 CSS 类，以突出显示代码单元格。这可以用于向代码单元格添加自定义样式。

plugins:
  - mkdocs-jupyter:
      highlight_extra_classes: "custom-css-classes

RequireJS

默认情况下，RequireJS 未加载。这是 Plotly 所必需的。您可以通过以下方式启用它

plugins:
    - mkdocs-jupyter:
          include_requirejs: true

下载笔记本链接

您可以让插件包含笔记本源，以便在主题中轻松显示下载按钮，默认为False

plugins:
    - mkdocs-jupyter:
          include_source: True

此设置还将创建一个page.nb_url值，您可以在主题中使用它来在每页创建一个链接。

例如，在 mkdocs-material 中（请参阅自定义），您可以创建一个如下的main.html文件

{% 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 %}

样式

此扩展包括 Jupyter Lab nbconvert CSS 样式，并对它进行了修改，使其尽可能通用，以便与各种 mkdocs 主题一起使用。这并不总是可能的，我们测试最多的主题是mkdocs-material。

您可能需要进行一些 CSS 修改，使其看起来尽可能好，例如，对于 material 主题，请参阅他们的自定义文档。

创建一个main.html文件如

{% extends "base.html" %}

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

<style>
// Do whatever changes you need here

.jp-RenderedHTMLCommon p {
    color: red
}

</style>
{% endblock content %}

Mkdocs Material 笔记

任何特定的 markdown 功能，如警告，都不会与 mkdocs-jupyter 一起工作，因为这些功能不是由 Jupyter 本身支持的，我们使用nbconvert进行转换。

要使用此类功能，您必须在 markdown 单元格中直接定义 HTML。

<div class="admonition note">
    <p class="admonition-title">Note</p>
    <p>
        If two distributions are similar, then their entropies are similar,
        implies the KL divergence with respect to two distributions will be
        smaller...
    </p>
</div>