目录只识别markdown cell中的#标题语法，代码块内#不会渲染为标题标签；toc插件依赖jupyter将markdown标题转为html heading标签，且标题格式必须严格（#后紧跟空格），安装后需执行install和enable命令并清除缓存。
不能直接给代码块（Code cell）添加目录索引 —— 目录只识别 Markdown cell 中的标题语法（#、## 等），代码块本身不会出现在 TOC 里。
为什么 # 标题 必须写在 Markdown cell 里
Table of Contents（TOC）插件（如 toc2）解析的是 HTML 渲染后的文档结构，它依赖 Jupyter 将 Markdown cell 中的 # 级别语法转为 <h1></h1>～<h6></h6> 标签。Code cell 的内容即使写了 # something，也只会被当作注释或字符串，不会触发标题渲染。
- 写在 Code cell 里的
# 数据预处理→ 不会生成任何 heading 标签，TOC 完全忽略 - 写在 Markdown cell 里的
# 数据预处理→ 渲染为<h1>数据预处理</h1>，自动加入目录 - 混用风险：把标题写成 Code cell 后再改 cell type 为 Markdown，有时样式残留，建议新建 Markdown cell 重输
jupyter_contrib_nbextensions 安装后 TOC 不显示的常见原因
装完插件、勾选了 Table of Contents (2)，但点右上角按钮没反应？大概率是这几处卡住了：
- 没运行
jupyter contrib nbextension install --user—— 这步把前端 JS/CSS 复制到用户配置目录，缺了就加载不了 TOC 面板 - Mac/Linux 用户漏了
jupyter nbextensions_configurator enable --user—— 否则 Nbextensions 标签根本不会出现在 Jupyter 顶部菜单 - 浏览器缓存了旧版 JS：强制刷新（
Ctrl+Shift+R或Cmd+Shift+R），或清空缓存后重启 notebook - 插件冲突：如果同时启用了
Collapsible Headings和toc2，某些老版本会互相干扰，可先禁用前者测试
标题层级和空格细节决定 TOC 是否生效
TOC 对 Markdown 标题格式极其敏感，一个空格不对就进不了目录：
- ✅ 正确：
# 数据加载、## 特征工程、### 模型评估（#后必须紧跟一个空格，再写文字） - ❌ 无效：
#数据加载（缺空格）、# 数据加载（# 前多空格）、## 二级标题（末尾多空格） - ⚠️ 注意：Jupyter 不支持中文标题自动锚点（如
# 中文标题生成的链接可能乱码），建议英文命名或混合使用（如# 1_数据清洗） - 标题需在独立的 Markdown cell 中 —— 同一个 cell 里写多个
#只会取第一个，其余被当普通文本
真正卡住人的地方不是“怎么装”，而是“装完发现点不动”或“标题写了却不在目录里”。核心就两条：确保标题在 Markdown cell 且格式零误差，以及确认前端资源已正确部署到 --user 路径下。其他都是枝节。
