nbconvert 是可控导出 HTML/PDF 的正确方式，支持剔除代码、指定模板、嵌入图片等；常见问题多因环境缺失（如 pdflatex）或参数错误（如漏 --to html），HTML 优先于 PDF 用于分享，美化推荐导出后注入 CSS。
用 nbconvert 命令行导出 HTML，别在 Notebook 里点“下载为”
Jupyter 自带的“File → Download as → HTML”生成的是带大量调试信息、无样式、无法自定义的原始页面，几乎不能当报告用。nbconvert 才是真正可控的导出方式，它默认调用内置模板，但支持指定主题、过滤输出、剔除代码单元等关键操作。
常见错误现象：nbconvert 导出空白页或报 TemplateNotFound 错误——通常因为没装 pip install jupyter_contrib_nbextensions 或漏了 --to html 参数；PDF 导出失败则大概率缺 pdflatex 环境。
- 基础命令：
jupyter nbconvert --to html --no-input report.ipynb（--no-input剔除代码块，只留输出和 Markdown） - 加样式更稳：
jupyter nbconvert --to html --no-input --template basic report.ipynb（basic模板轻量、兼容性好，比默认lab模板更少报错） - 想嵌入本地图片或 CSS？必须加
--embed-images，否则 HTML 里全是相对路径，打开即 404
导出 PDF 时 LaTeX 报错：不是 Notebook 的问题，是系统缺编译链
PDF 导出本质是把 Notebook 转成 LaTeX 再调 pdflatex 编译。Jupyter 不自带 LaTeX，所以 nbconvert --to pdf 失败，99% 是环境问题，不是代码写错了。
使用场景：需要打印、提交正式文档、插入公式且要求排版精准时才用 PDF；日常分享优先选 HTML —— 加载快、字体保真、图表交互保留。
立即学习“Python免费学习笔记（深入）”；
- Mac 用户装 MacTeX（别用 BasicTeX，缺
ucs包易报错）；Windows 用 MiKTeX（勾选“始终安装缺少的包”） - 验证是否就绪：
pdflatex --version能返回版本号，且which pdflatex有输出 - 仍报
! Package inputenc Error: Unicode char …？加参数：--pdf-engine=xelatex，并确保 Notebook 元数据里设了"kernelspec": {"name": "python3", "language": "python"}
让 HTML 报告“看起来像报告”：改 CSS 比换模板更直接
官方模板（basic / classic）样式简陋，但硬套第三方模板（如 jupyter-sphinx）反而容易破坏数学公式渲染或交互图表。最可靠的方式是导出后手动注入 CSS，或用 --CSSHTMLHeader 注入内联样式。
性能影响：大报告（>50 个 cell）加复杂 CSS 动画会拖慢加载；兼容性上，@media print 规则对 PDF 导出无效，只作用于 HTML 浏览器打印。
- 快速美化标题和字体：
jupyter nbconvert --to html --no-input --HTMLExporter.exclude_input=True --HTMLExporter.template_name=basic report.ipynb，再用--HTMLExporter.extra_template_basedirs指向含自定义custom.css的目录 - 更省事：导出后用 Python 读取 HTML 文件，用
BeautifulSoup插入<style></style>块，改h1字重、表格边框、代码块背景色 - 注意：MathJax 渲染的公式不能被 CSS 直接改字号，得用
tex2jax_process配置或改mathjax_config
图表和交互元素在导出后消失？检查输出格式和前端依赖
Plotly、Bokeh、Altair 图表在 HTML 中正常，但导出 PDF 时必然丢失（PDF 不支持 JS），而 HTML 中若图表不显示，90% 是因为导出时没保留 application/vnd.plotly.v1+json 这类 MIME 输出，或 CDN 资源被拦截。
使用场景：分析报告需交付给非技术人员，优先用 Matplotlib 静态图 + plt.savefig 保存高分辩 PNG；要交互就只发 HTML，并附说明“请用 Chrome/Firefox 打开”。
- Plotly 必须显式调用
fig.write_html("plot.html")或设置config={"responsive": True}，否则 nbconvert 只存 JSON，不触发 JS 初始化 - Bokeh 需提前运行
output_file()或save()，不能只靠show()；否则导出 HTML 里只有空 div - Altair 要加
alt.renderers.enable('default')并确保vega-liteCDN 在导出 HTML 的里正确引入
真正麻烦的不是怎么导出，而是导出后打开发现公式错位、表格溢出、中文字体变成方块——这些细节没标准解法，得一个个看浏览器开发者工具里的 network 和 console。
