将 nbconvert 作为命令行工具使用

运行 nbconvert 脚本的命令行语法是：

jupyter nbconvert --to FORMAT notebook.ipynb

这会把 Jupyter Notebook 文件 notebook.ipynb 转换为 FORMAT 字符串指定的输出格式。

默认输出格式

在 nbconvert 5.x 中，默认输出格式是 HTML。6.0 移除了默认值，命令行调用必须明确设置 --to 参数才能执行。要模拟原来的5.x行为，应在 jupyter nbconvert 命令中添加 --to=html。

支持的输出格式

当前支持 HTML、LaTeX、PDF、WebPDF、Reveal.js HTML 幻灯片、Markdown、Ascii、reStructuredText、可执行脚本和 Notebook。

Jupyter 还为输出格式提供了一些模板。通过额外的 --template 参数指定，下面各节列出这些模板。

HTML

--to html

导出 HTML。关于向后兼容：如果此前使用了5.x旧模板文件的自定义副本，即通过 --template 指定，现在需要使用 --template-file path/to/old/file.tpl，才能以兼容模式使用该文件。

--template lab（默认）：完整的静态 HTML 渲染，外观与 JupyterLab 的交互视图非常相似。
--template classic：简化的 HTML，采用经典 Jupyter 的外观。
--template basic：基础 HTML，结构和样式尽量少。
--embed-images：提供该选项时，会将图片以 base64 URL 嵌入生成的 HTML 文件。

lab 模板支持额外的 --theme 选项，默认是 light。除了 JupyterLab 提供的 light、dark，还可以使用自定义主题。例如先执行 pip install jupyterlab-miami-nights，再指定 --theme jupyterlab_miami_nights。

LaTeX

--to latex

导出 LaTeX。生成可继续导出的 NOTEBOOK_NAME.tex 文件；图片以 .png 文件输出到文件夹中。

--template article（默认）：LaTeX article 模板，基于 Sphinx 的 howto 模板。
--template report：LaTeX report 模板，提供目录和章节。

可以选择在 Notebook 元数据中指定 authors、title、date，它们用于渲染 LaTeX 文档的页首：

{
    "authors": [
        {"name": "Jane Doe"},
        {"name": "John Doe"}
    ],
    "date": "January 2023",
    "title": "Annual Data Report 2022",
    "kernelspec": {},
    "language_info": {}
}

若未指定日期，会使用当天日期，即文档编译或重新编译的日期。设为空字符串则不显示日期。

Notebook 中的值可以由 --LatexPreprocessor.title、--LatexPreprocessor.date 和 --LatexPreprocessor.author_names 命令行参数覆盖。每位作者分别指定一次 author_names。

注意：nbconvert 使用 pandoc 在不同标记语言之间转换，因此转换到 LaTeX 或 reStructuredText 时依赖 pandoc。

PDF

--to pdf

通过 LaTeX 生成 PDF。支持与 --to latex 相同的模板。

WebPDF

--to webpdf

先渲染为 HTML，再使用无头 Chromium 渲染 HTML 并导出 PDF。此导出器支持与 --to html 相同的模板。

WebPDF 导出器需要 playwright Chromium 自动化库，可以通过 nbconvert[webpdf] 安装。

Reveal.js HTML 幻灯片

注意：要指定 Notebook 单元格与 Reveal.js 幻灯片的映射，在 Jupyter Notebook 中选择 View → Cell Toolbar → Slideshow。每个单元格右上角会出现下拉菜单，可以选择 Slide、Sub-Slide、Fragment、Skip、Notes。转换时，标记为 skip 的单元格不会包含在输出中，notes 只出现在演讲者备注中。

--to slides

这会生成 Reveal.js HTML 幻灯片。运行幻灯片需要一份 reveal.js，原文要求版本4.x。

默认情况下，生成的 HTML 包含 script 标签，直接从公共 CDN 加载 reveal.js。因此，将幻灯片放在网页上时，通常能按预期运行。但演讲者备注、计时器等功能需要 reveal.js 的本地副本，不能仅靠这种网页加载方式运行。

演讲者备注需要本地 reveal.js，然后要告诉 nbconvert 怎样找到它。计时器不仅需要先配置好演讲者备注，还需要本地 HTTPS 服务器。详见下面的服务器示例。

示例：创建带演讲者备注的幻灯片

假设有一个 your_talk.ipynb，希望把它转换为幻灯片。本例假设当前工作目录与 Notebook 文件所在目录相同，即执行 ls . 时能在文件列表中看到 your_talk.ipynb。

首先，需要将一份 reveal.js 放在与幻灯片相同的目录中。一种方法是在终端执行以下命令：

git clone https://github.com/hakimel/reveal.js.git
cd reveal.js
git checkout 3.5.0
cd ..

然后，通过 --reveal-prefix 命令行标志告诉 nbconvert 使用这个本地副本：

jupyter nbconvert your_talk.ipynb --to slides --reveal-prefix reveal.js

生成的文件是 your_talk.slides.html，可通过 open your_talk.slides.html 打开。幻灯片加载后，按 s，演讲者备注应在新窗口中打开。

注意：这并不意味着幻灯片完全离线运行。即使 reveal.js 已在本地，幻灯片默认仍通过公共 CDN 访问 mathjax、require、jquery。支持这一用法仍是一个待解决的问题，欢迎提交 PR。

通过 HTTPS 服务器提供幻灯片：`--post serve`

演讲者备注正常工作后，你可能发现计时器仍不工作。它需要额外的基础设施：通过本地 HTTPS 服务器提供本地 reveal.js。

nbconvert 的 ServePostProcessor 让这件事相对简单。要启用服务器，在 nbconvert 命令末尾添加 --post serve：

jupyter nbconvert your_talk.ipynb --to slides --reveal-prefix reveal.js --post serve

服务器会占用执行命令的终端，直到停止。连续按两次 Ctrl+C 可以停止它。

Markdown

--to markdown

输出简单的 Markdown。Markdown 单元格保持不变，代码单元格缩进4个空格；图片以 .png 文件输出到文件夹中。

Ascii

--to asciidoc

输出 Ascii，图片以 .png 文件输出到文件夹中。

reStructuredText

--to rst

输出基础的 reStructuredText，可作为把 Notebook 嵌入 Sphinx 文档的起点；图片以 .png 文件输出到文件夹中。

注意：转换为 LaTeX 或 reStructuredText 时，nbconvert 依赖 pandoc。

可执行脚本

--to script

把 Notebook 转换为可执行脚本。这是从 Notebook 中取得 Python 脚本，或取得内核所使用的其他语言脚本，最简单的方法。如果 Notebook 中包含魔法命令，生成的脚本可能只能在 Jupyter 会话中执行。

例如，将 Julia Notebook 转换为 Julia 可执行脚本：

jupyter nbconvert --to script my_julia_notebook.ipynb

Notebook 与预处理器

--to notebook

此功能在3.0中加入。

它本身不会把 Notebook 转换为不同的格式，而是允许运行 nbconvert 预处理器，或转换为其他版本的 Notebook 格式。例如：

jupyter nbconvert --to notebook --execute mynotebook.ipynb

这会打开 Notebook、执行它、捕获新的输出，并将结果保存为 mynotebook.nbconvert.ipynb。指定 --inplace 会覆盖输入文件，而不是写入新文件。

默认情况下，只要某个单元格执行时出现异常，nbconvert 就会终止转换。在 --execute 之外指定 --allow-errors，转换会继续，异常输出也会包含在单元格输出中。

下面的命令会以 Notebook 格式版本3，把 mynotebook.ipynb 的副本保存为 mynotebook.v3.ipynb：

jupyter nbconvert --to notebook --nbformat 3 mynotebook

若要就地转换 Notebook，可以把输出文件指定为输入文件的名称：

jupyter nbconvert --to notebook mynb --output mynb

这会替换输入文件，请留意。

注意：转换为 LaTeX 或 reStructuredText 时，nbconvert 依赖 pandoc。

nbconvert 创建的输出文件与 Notebook 使用相同的基本名称，并放在当前工作目录。图形等支持文件会放在名称相同、带 _files 后缀的新目录中。原文展示的目录形式为：

jupyter nbconvert notebook.ipynb
ls

notebook.ipynb   notebook.html    notebook_files/

对于 HTML、Markdown 等简单的单文件输出，可以输出到标准输出：

jupyter nbconvert --to markdown notebook.ipynb --stdout

转换多个 Notebook

可以在命令行中指定多个 Notebook：

jupyter nbconvert notebook*.ipynb
jupyter nbconvert notebook1.ipynb notebook2.ipynb

也可以通过配置文件中的列表指定。例如，在 mycfg.py 中写入：

c = get_config()
c.NbConvertApp.notebooks = ["notebook1.ipynb", "notebook2.ipynb"]

再执行：

jupyter nbconvert --config mycfg.py

原文：Using as a command line tool，nbconvert 7.17.1 文档。作者：Jupyter Development Team。本文为中文翻译，保留原文命令及版本条件；原文关于 reveal.js 4.x 的说明和示例中的3.5.0保持原样。© 2001-2015 IPython Development Team；© 2015- Jupyter Development Team。采用 BSD 3-Clause 许可，完整条件及免责声明随许可文本保留。

完整许可证原文

BSD 3-Clause License

- Copyright (c) 2001-2015, IPython Development Team
- Copyright (c) 2015-, Jupyter Development Team

All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

文章版权归作者所有，未经允许请勿转载。

THE END