解决Jupyter Book在GitHub Pages上的侧边栏异常问题

• 检查GitHub Pages部署源配置
  确认GitHub Pages的部署分支和目录是否匹配Jupyter Book的构建输出。Jupyter Book默认将静态文件生成在_build/html目录，所以要确保部署源选择的是gh-pages分支（自动部署场景），或是主分支的_build/html目录（手动上传场景）。目录选错会导致CSS、JS等资源路径错误，直接引发样式异常。

• 修正资源路径配置
  如果你的仓库是项目仓库（非用户/组织主页仓库），GitHub Pages的基础URL会是https://<username>.github.io/<repo-name>/，而本地构建时用的是根路径。需要在_config.yml中添加html_baseurl: "/<repo-name>/"，替换<repo-name>为你的仓库名称，重新构建后再上传文件。
  可以打开浏览器控制台（F12）查看网络请求，若存在CSS、图标文件的404错误，就说明路径配置有问题，调整baseurl后即可解决。

• 确认构建文件完整上传
  即使.gitignore只忽略了.log和_build，手动上传时也可能遗漏_static、_templates这类子文件夹。建议用git add _build/html/**命令强制添加所有构建文件，再提交推送到GitHub，确保样式、图标等资源文件完整上传。

• 更新Jupyter Book并规范构建流程
  先升级到最新稳定版：pip install --upgrade jupyter-book，避免版本兼容问题。然后用标准命令构建：jupyter-book build docs/（假设你的书源文件在docs目录），确保构建过程无报错，生成的_build/html目录完整。

• 改用GitHub Actions自动部署
  手动上传容易出错，推荐用GitHub Actions自动化部署。在仓库中创建.github/workflows/deploy.yml文件，内容如下：

  name: Deploy Jupyter Book to GitHub Pages
  on:
    push:
      branches: [ main ]  # 替换成你的主分支名称
  jobs:
    deploy:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
          with:
            fetch-depth: 0
        - name: Set up Python
          uses: actions/setup-python@v5
          with:
            python-version: '3.10'
        - name: Install dependencies
          run: |
            pip install jupyter-book
            pip install ghp-import
        - name: Build the book
          run: jupyter-book build docs/
        - name: Deploy to GitHub Pages
          run: ghp-import -n -p -f docs/_build/html
  

  提交该配置后，GitHub会自动构建并部署到gh-pages分支，再在GitHub Pages设置中选择gh-pages分支作为部署源即可。

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