Jupyter Notebook本地内部链接正常，GitHub Pages托管后失效如何解决？

问题原因 #

本地运行时，Jupyter Notebook的内部锚点链接基于当前文件路径直接跳转，但托管到GitHub Pages后，站点URL带有仓库名称前缀，且GitHub渲染Notebook时的锚点格式可能与本地略有差异，导致链接跳转到仓库首页。

具体修复步骤 #

• 检查并修正锚点格式
  GitHub渲染Notebook时，章节标题会被转换为小写、空格替换为短横线的锚点ID。比如标题1. 数据预处理对应的锚点是#1-数据预处理。你可以打开GitHub上的Notebook页面，右键章节标题选择“检查”，查看对应<h1>/<h2>标签的id属性，将内部链接的锚点部分改为匹配的#id值。

• 避免使用绝对路径
  不要写以/开头的绝对路径链接（比如/your-notebook.ipynb#章节），这种写法会跳转到GitHub Pages的根域名首页。改用相对路径：

  • 同一页面内的锚点直接写#锚点ID
  • 跨Notebook的链接写相对路径，比如../another-notebook.ipynb#锚点ID

• 使用nbconvert导出标准HTML文件
  若直接托管.ipynb文件仍有问题，可将Notebook导出为HTML后再上传：

  1. 执行命令导出带完整锚点的HTML：

     jupyter nbconvert --to html --template full your-notebook.ipynb
     

  2. 将生成的your-notebook.html上传到GitHub仓库，设置GitHub Pages指向该文件所在分支（如gh-pages）
  3. 此时HTML文件的内部链接会直接适配GitHub Pages的路径，无需额外修改锚点

• 验证链接有效性
  上传后打开GitHub Pages页面，点击内部链接测试跳转，若仍有问题，查看浏览器地址栏的变化，确认链接是否指向正确的页面和锚点位置。

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