4.2 导出与分享格式

4.2 导出与分享格式

本节摘要：SOURCE 4.2 列 HTML/PDF/Markdown/Python/rst 等导出目标，以及界面 Download as 与 jupyter nbconvert 命令行。本节保留原文 nbconvert 示例，并补充导出前清理输出、标题目录等分享技巧。

阅读收获

阅读完本节，你应当能够：

1. 从 Notebook 菜单选择 Download as 常见格式
2. 用 nbconvert --to html/pdf/markdown/script 批转换
3. 导出前移除不必要输出以减小体积
4. 为长 Notebook 添加 Markdown 标题层级便于导航

一、常见导出格式

SOURCE 对比：

二、nbconvert 命令行

SOURCE 示例：

jupyter nbconvert --to html notebook.ipynb
jupyter nbconvert --to pdf notebook.ipynb
jupyter nbconvert --to markdown notebook.ipynb
jupyter nbconvert --to script notebook.ipynb
​

PDF 依赖系统 TeX（如 MiKTeX）——Windows 上失败时先改导出 HTML 再浏览器打印为 PDF。

三、界面导出

File → Download as → HTML / PDF / Markdown 等——与 nbconvert 等价，适合单次分享。JupyterLab 用 File → Export Notebook As。

四、分享技巧（SOURCE 4.2.3）

• 清晰标题与首段说明：读者 30 秒内知道目的
• 代码注释 + Markdown 解释：别只丢代码格
• 导出前 Clear Output：减小 HTML/PDF 体积（静态图仍可在重新 Run All 后导出）
• 长文用 Markdown 标题 1–6：配合第 5 章 Table of Contents 扩展

⚠️ 常见坑：nbconvert 不会执行 Notebook——未运行的格导出为空输出；分享前 Run All 再导出。

💡 关键直觉：HTML 给「看」；script 给「复用代码」；ipynb 给「继续协作」——按受众选格式。

要点串联

• HTML/PDF/MD/py：不同受众
• jupyter nbconvert --to ...
• Run All + Clear 策略：看场景
• 标题与说明：降低阅读成本

下一节 4.3 协作工具与平台 讲 GitHub 与 JupyterHub。

按受众选导出格式

导出前必做的三件事

1. Run All：确保每个单元格都有输出，nbconvert 不执行代码。
2. 核对标题层级：Markdown 用 1–6 级标题组织，导出目录才清晰。
3. 检查输出体积：大图或 plotly 交互是否会让文件膨胀到不便于传输。

批量导出的实用写法

for nb in notebooks/*.ipynb; do
  jupyter nbconvert --to html "$nb" --output-dir dist/
done
​

Windows 环境用 PowerShell 的 Get-ChildItem 加 ForEach-Object 等价写法，或在 Git Bash 中运行上面的循环。批量导出前先导一份看样式，再全量跑。

保留元数据的导出

nbconvert 默认不执行、不保留运行时输出之外的信息。若需要把内核名、依赖版本写进导出物，可以在 Notebook 首个 Markdown 格里固定维护一段"环境说明"文字，导出后自然带过去。这也是 4.3 节"README 写版本号"思路的变体。

导出自定义模板

nbconvert 支持 --template 参数。团队可以写一个带统一页眉、页脚与样式的 HTML 模板，导出报告保持品牌一致。模板文件通常放在项目 templates/ 目录，用 nbconvert 的 --template-file 指定。

jupyter nbconvert --to html notebook.ipynb --template-file templates/report.html.j2
​

导出物与源文件的对应

导出的 HTML/PDF 只是快照。建议在导出物首页 Markdown 格里写明"来源 ipynb 路径、内核版本、导出时间"，同事拿到 HTML 后能顺藤摸瓜找到源头，而不是面对一份不知从哪来的报告。

分享前的最后检查

• 机密数据是否被图中坐标轴或输出泄露（列名、数值、人员信息）。
• 图表字体与中文是否正常渲染。
• 目标受众能否直接打开（HTML 无需环境，PDF 需阅读器）。
• 是否保留了清晰的标题与首段说明。

导出物的一致性检查

正式对外分享前，建议做一次"观众视角"检查：把导出的 HTML 交给一个没参与项目的人，看 TA 能否在五分钟内讲出这份报告讲什么。讲不出，通常不是文笔问题，而是结构问题——Markdown 标题层级不清、结论格缺失、图没有标题。先改结构再重新导出，比反复调模板样式有效。

版本号与导出记录

给导出的报告加一个简单版本号（如 v1.2），并把导出日期、对应 ipynb 提交哈希写进首页。这样业务方反馈问题时，你能快速定位到他们看的是哪一版，避免"你改的怎么跟我看的不一样"的来回拉扯。

导出前的运行状态确认

nbconvert 不执行代码，所以导出前必须确认 Notebook 处于"全格已运行"状态。最稳妥的顺序是：先 Restart & Run All 看是否一次通过，再 Clear Output 清掉中间过程的临时输出，最后根据需要选择保留哪些输出重新运行或直接导出。

格式选择背后的成本

每种格式都有维护成本：HTML 每改一次内容要重新导出，PDF 要装 LaTeX，Markdown 要重新处理图片路径。选格式时把"更新频率"考虑进去——经常改的报告用 HTML 模板加脚本批量生成，一次性材料用 PDF 固定下来。

导出流程的固定化

同一份报告反复导出时，把导出命令存成脚本或写进 README，避免每次手工敲命令、参数不一致。固定的导出流程还意味着团队成员都能跑出相同结果，版本差异最小化。

分享前的受众提问

导出前先问一句：读者要做什么决定？答案决定内容取舍。给决策者看结论摘要与关键图，给执行者看步骤与代码可复现性。同样的 Notebook，两种受众的导出物可以完全不同。