mknotebooks

mknotebooks是一个MkDocs插件，它允许您直接在项目文档中包含MkDocs笔记本。

安装

pip3 install mknotebooks

用法

• 将mknotebooks添加到mkdocs.yml的插件部分。
• 将您想要使用的任何笔记本（.ipynb文件）添加到docs/目录中，就像添加.md文件一样。

示例

# mkdocs.yml
nav:
  - your_notebook.ipynb

plugins:
  - mknotebooks

任何静态图像、图表等将从笔记本中提取并放置在输出HTML旁边。

选项

您可以选择执行笔记本，通过在配置中设置execute: true。您可以通过preamble: "<path/to/your/script>"包含一个隐藏的前置脚本，在执行任何单元格之前运行。默认单元格执行超时可以通过设置timeout: <timeout>来覆盖，其中<timeout>是一个整数秒数。

默认情况下，如果任何单元格抛出错误，将终止执行，但您可以通过设置allow_errors: true来继续执行并将错误消息包含在单元格输出中。

示例

# mkdocs.yml
plugins:
  - mknotebooks
      execute: false
      timeout: 100
      preamble:  "<path/to/your/script>"
      allow_errors: false

样式

Mknotebooks应用默认样式以改善笔记本输入/输出单元格和pandas数据框的外观。如果它们与您正在使用的任何其他CSS样式表冲突，您可以通过以下选项禁用这些样式。

# mkdocs.yml
- mknotebooks:
   enable_default_jupyter_cell_styling: false
   enable_default_pandas_dataframe_styling: false

语法高亮显示

为了启用代码块的语法高亮显示，必须安装 pygments 并在 mkdocs.yml 中启用 codehilite 扩展。

1. 安装 pygments

pip install Pygments

2. 在 mkdocs.yml 中启用 codehilite 扩展

# mkdocs.yml
markdown_extensions:
    - codehilite

Binder

您还可以选择让 mknotebooks 在每个笔记本中插入一个 Binder 链接。

- mknotebooks:
      binder: true
      binder_service_name: "gh"
      binder_branch: "master"
      binder_ui: "lab"

如果您正在使用 GitLab，则需要将 binder_service_name 设置为 "gl"。

示例

请参阅 示例文件夹 了解关于使用 序言 和 使用 Binder 的示例。通过运行 pipenv install && pipenv run mkdocs serve 来尝试它们。

检查生成的 markdown

您还可以通过在您的 mkdocs.yml 中设置 write_markdown: true 来导出生成的 markdown。这将把生成的 markdown 写入与原始笔记本并排的 .md.tmp 文件中。