如何为nbconvert生成的HTML文档定制主题与样式？

一、创建nbconvert可直接调用的自定义主题 #

不需要依赖cookiecutter，直接基于nbconvert的Jinja2模板体系手动搭建即可，步骤如下：

• 先定位nbconvert的模板根目录：
  运行jupyter --paths查看输出里的data路径，对应的nbconvert/templates就是模板存放目录，conda环境下一般是~/.conda/envs/my-env/share/jupyter/nbconvert/templates/
• 创建自定义主题目录，比如命名为my-custom-theme，目录结构对齐默认的lab模板：

  my-custom-theme/
  ├── static/
  │   └── theme.css  # 你的自定义样式文件
  ├── template.html.j2  # 继承lab模板的Jinja2模板文件
  └── conf.json  # 主题配置文件
  

• 编写conf.json，指定主题的基础模板和标识：

  {
    "base_template": "lab",
    "theme": "my-custom-theme",
    "display_name": "我的自定义主题"
  }
  

• 编写template.html.j2，继承lab模板并引入自定义CSS：

  {% extends 'lab/template.html.j2' %}
  
  {% block extra_head %}
    {{ super() }}
    <link rel="stylesheet" href="{{ static_url('theme.css') }}">
  {% endblock %}
  

• 在static/theme.css里写入你的自定义样式，比如：

  body {
    font-family: "Segoe UI", Roboto, sans-serif;
    font-size: 16px;
    line-height: 1.6;
  }
  .jp-MarkdownOutput p {
    margin: 0.8em 0;
  }
  

• 验证主题：运行命令jupyter nbconvert --to html --no-input --theme my-custom-theme my.ipynb，生成的HTML就会应用你的主题样式

二、将自定义CSS纳入nbconvert输出的几种实用方法 #

方法1：通过极简自定义模板注入 #

如果不需要完整主题，只想快速添加CSS，可创建一个极简模板：

• 新建一个模板目录（比如custom-css-template），里面只放template.html.j2：

  {% extends 'lab/template.html.j2' %}
  
  {% block extra_head %}
    {{ super() }}
    <style>
      /* 直接在这里写自定义CSS */
      body { font-family: "Arial", sans-serif; font-size: 15px; }
      .jp-Cell { margin: 1em 0; }
    </style>
  {% endblock %}
  

• 使用时指定模板：jupyter nbconvert --to html --no-input --template custom-css-template my.ipynb

方法2：在Python自动化脚本中直接注入 #

既然你已经用Python脚本自动化后两步，可直接在脚本里配置HTMLExporter来注入CSS：

from nbconvert import HTMLExporter
import nbformat

# 读取目标notebook
nb = nbformat.read('my.ipynb', as_version=4)

# 初始化HTMLExporter，指定lab模板
exporter = HTMLExporter(template_name='lab')

# 直接把自定义CSS写入extra_head
exporter.extra_head = """
<style>
  body { font-family: "Helvetica Neue", Helvetica, sans-serif; font-size: 16px; }
  .jp-Cell-input { display: none; } /* 替代--no-input参数的效果 */
  .jp-MarkdownOutput h2 { color: #2c3e50; border-bottom: 1px solid #eee; }
</style>
"""

# 生成HTML并保存
html_content, resources = exporter.from_notebook_node(nb)
with open('my.html', 'w', encoding='utf-8') as f:
    f.write(html_content)

方法3：修改全局lab模板（不推荐） #

如果想让所有用lab主题的输出都带上自定义CSS，可修改全局的lab模板：
找到~/.conda/envs/my-env/share/jupyter/nbconvert/templates/lab/template.html.j2，找到{% block extra_head %}区块，添加你的CSS代码。但要注意：conda环境更新时，这个文件可能会被覆盖，所以不推荐这种方式。

内容的提问来源于stack exchange，提问作者TheIdealis