---
jupyter:
  kernelspec:
    display_name: Python
    language: python
    name: python3
---

(file-types:custom)=
# 自定义笔记本格式和 Jupytext

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

:::{tip}
本页本身就是一个 [RMarkdown](https://rmarkdown.rstudio.com/) 笔记本！
:::

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

- 该字符串应该是一个 Python 函数，它将由 `import mylibrary.converter_function` 加载
- 该函数应该接受文件的内容（以 `str` 形式）并返回 [nbformat.NotebookNode](nbformat:api)

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

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

:::{important}

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

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

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

:::

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

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

此映射允许 "true" 错误报告，如 [](myst-nb:start/error-reporting) 中所述。

## 使用 Jupytext

[Jupytext](https://jupytext.readthedocs.io/en/latest/) 是一个优秀的 Python 工具，用于在 Jupyter Notebook `.ipynb` 文件和[各种基于文本的文件](https://jupytext.readthedocs.io/en/latest/formats.html)之间进行双向转换。

Jupyter Book 原生支持 Jupytext 文件格式：[带有 MyST Markdown 的笔记本](./myst-notebooks.md)，但你可以添加其他格式，如 [RMarkdown](https://rmarkdown.rstudio.com/) 或 Python 文件。

配置看起来像这样：

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

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

现在你可以使用 RMarkdown 块：

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

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

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

(file-types:custom:jupytext)=
## 将一个 Jupytext 文件转换为 MyST 笔记本

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

```bash
jupytext --to myst path/to/yourfile
```

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

```bash
jupytext --to myst ./*.py
```

更多信息请参见 [Jupytext CLI 文档](https://jupytext.readthedocs.io/en/latest/using-cli.html)。
