Contents

自定义笔记本格式和 Jupytext

您可以指定将其他文件类型转换为笔记本，然后以与常规笔记本相同的方式执行/解析。

小技巧

本页本身就是一个 RMarkdown 笔记本！

sphinx:
  config:
    nb_custom_formats:
        .mysuffix: mylibrary.converter_function

  • 该字符串应该是一个 Python 函数，它将由 import mylibrary.converter_function 加载

  • 该函数应该接受文件的内容（以 str 形式）并返回 nbformat.NotebookNode

如果函数接受其他关键字参数，则可以在第二个参数中指定这些关键字作为字典。例如，这是默认转换的样子：

sphinx:
  config:
    nb_custom_formats:
        .ipynb:
            - nbformat.reads
            - as_version: 4

重要

默认情况下，笔记本中的 Markdown 单元格将使用与其他 Markdown 文件相同的 MyST 解析器配置进行解析。

但是，如果这与你的文件格式不兼容，那么你可以指定 Markdown 被严格地解析为 CommonMark，使用第三个参数：

sphinx:
  config:
    nb_custom_formats:
        .ipynb:
            - nbformat.reads
            - as_version: 4
            - true

最后，对于基于文本的格式，MyST-NB 还在输出笔记本的元数据中搜索一个可选的 source_map 键。这个键应该是一个列表，将每个单元格映射到原始源文件的起始行号，例如一个有三个单元格的笔记本：

{
  "metadata": {
    "source_map": [10, 21, 53]
  }
}

此映射允许 “true” 错误报告，如 中所述。

使用 Jupytext

Jupytext 是一个优秀的 Python 工具，用于在 Jupyter Notebook .ipynb 文件和各种基于文本的文件之间进行双向转换。

Jupyter Book 原生支持 Jupytext 文件格式：带有 MyST Markdown 的笔记本，但你可以添加其他格式，如 RMarkdown 或 Python 文件。

配置看起来像这样：

sphinx:
  config:
    nb_custom_formats:
        .Rmd:
            - jupytext.reads
            - fmt: Rmd

警告

请注意，有些执行特性（比如 RMarkdown 中的内联代码执行）在 Jupyter Book 中是不可用的。

现在你可以使用 RMarkdown 块：

```{python echo=TRUE}
print("Hallo I'm an RMarkdown block!")
```

print("Hallo I'm an RMarkdown block!")

Hallo I'm an RMarkdown block!

重要

为了与 myst-parser 完全兼容，必须使用 jupytext>=1.6.0。

将一个 Jupytext 文件转换为 MyST 笔记本

或者，如果你想把你之前存在的 Jupytext 文件转换成 MyST 笔记本的格式，直接在你的书中使用，安装 Jupytext，然后运行以下命令：

jupytext --to myst path/to/yourfile

请注意，您还可以传递一个通配符，它将用于转换多个文件。例如：

jupytext --to myst ./*.py

更多信息请参见 Jupytext CLI 文档。