Jupyter Book构建后TOC导航不显示且报toctree相关警告如何排查？

1. 校验_toc.yml路径配置 #

• 所有file字段后的路径需为相对于项目根目录的相对路径，不要加.ipynb/.md后缀，路径大小写必须和实际文件完全一致（GitHub Pages为Linux环境，大小写敏感）。
• 确认首行root指定的入口文件真实存在，该文件是TOC的根节点，缺失会直接导致导航整体失效。

2. 检查_toc.yml语法格式 #

• 缩进必须使用2个空格，禁止用Tab键，各层级条目的缩进量要严格匹配导航层级。
• 所有配置项必须用英文冒号，冒号和值之间必须留1个空格，不要有多余的换行或特殊字符。

3. 排查_config.yml配置冲突 #

• 确认exclude配置项没有把需要加入TOC的源文件纳入排除列表。
• 检查是否有TOC相关的配置项意外关闭了全局导航展示。

4. 清理缓存重新构建 #

• 先删除项目下的_build文件夹，再执行jupyter-book build .重新编译，旧缓存会导致路径识别异常。

5. 校验源文件元数据 #

• 检查所有要加入TOC的源文件头部，确认没有配置orphan: true的元数据，该标记会让文件跳过toctree关联逻辑。

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