Use Jupyter Notebook in mkdocs
mkdocs-jupyter：在 mkdocs 中使用 Jupyter 笔记本
- 文档演示站点
- 直接将 Jupyter 笔记本添加到 mkdocs 导航
- 支持多种格式：
.ipynb和.py文件（使用 jupytext）
- 与常规 Jupyter 笔记本相同的样式
- 支持 Jupyter 主题
- 可选择在转换前执行笔记本
- 支持 ipywidgets
- 支持 mkdocs 目录（TOC）
- 可选择包含笔记本源代码
安装
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
标题和目录
Notebook 中的第一个 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
如果您想在 TOC 中嵌套标题，需要在同一个 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
您也可以仅隐藏 In[#] 和 Out[#] 提示，但保留输入和输出内容：
plugins:
- mkdocs-jupyter:
no_prompt: 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 %}
缓存
默认情况下，插件会缓存笔记本的转换结果，因此未更改的笔记本不会在每次构建时重新转换。缓存键基于笔记本文件内容和所有相关的插件配置选项。
要禁用缓存：
plugins:
- mkdocs-jupyter:
cache: false
要更改缓存目录（默认目录为 .cache/mkdocs-jupyter）：
plugins:
- mkdocs-jupyter:
cache_dir: .cache/custom-dir
之前构建中过时的缓存条目会被自动清理。
样式
此扩展包含 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>