Sphinx生成文档目录点击折叠下方页面时跳转至顶部问题求助

问题确认 #

这是sphinx_rtd_theme（Read the Docs主题）的已知兼容性bug，在你使用的v3.4.3和测试的v4.4.0版本中均存在。问题根源是主题侧边栏的滚动逻辑有缺陷，点击超出可视区域的页面链接时，会错误触发侧边栏滚动位置重置，导致目录跳回顶部。

修复方案 #

方法1：自定义JS补丁（最直接有效） #

因为不能升级Sphinx或更换主题，直接通过自定义JS覆盖主题的错误逻辑：

1. 在项目的_static目录新建fix_sidebar_scroll.js，写入以下代码：

document.addEventListener('DOMContentLoaded', function() {
  const sidebar = document.querySelector('.wy-side-scroll');
  if (!sidebar) return;

  // 拦截侧边栏一级页面链接的点击事件，保留当前滚动位置
  const sidebarLinks = sidebar.querySelectorAll('.toctree-l1 a');
  sidebarLinks.forEach(link => {
    link.addEventListener('click', function() {
      const currentScroll = sidebar.scrollTop;
      // 延迟恢复滚动位置，确保页面跳转完成后生效
      setTimeout(() => {
        sidebar.scrollTop = currentScroll;
      }, 100);
    });
  });
});

2. 在conf.py里添加这个JS文件的引用：

html_static_path = ['_static']
html_js_files = [
    'fix_sidebar_scroll.js',
]

方法2：配合CSS优化侧边栏滚动 #

如果JS补丁效果不够完美，再加个CSS调整固定侧边栏高度，减少异常触发：

1. 在_static目录新建custom.css，写入：

.wy-side-scroll {
  height: 100vh;
  overflow-y: auto;
}
.wy-nav-side {
  height: 100vh;
  overflow: hidden;
}

2. 在conf.py里添加CSS引用：

html_css_files = [
    'custom.css',
]

方法3：RTD平台构建设置调整 #

如果你的文档是在Read the Docs平台构建发布，试试在项目构建设置里：

• 启用“Build with Sphinx >= 4.x”选项（虽然本地测试v4.4.0有问题，但平台的主题环境可能有兼容修复）
• 确保勾选“Use the Read the Docs theme”并使用平台提供的最新兼容版本

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