Sphinx文档toctree点击跳转至导航锚点而非页面顶部求助

当点击Sphinx文档的toctree导航项时，页面会直接跳转到目标页的toc元素位置而非顶部，导致跳转突兀。以下是几种可行的解决方法：

方法1：自定义JS强制页面加载时回到顶部 #

1. 在项目的_static目录下新建fix_scroll.js文件，写入代码：

window.addEventListener('load', () => {
    const hash = window.location.hash;
    // 匹配toc相关的锚点（根据你的主题实际锚点id调整）
    if (hash && (hash === '#contents' || hash.startsWith('#toc-'))) {
        // 滚动到页面顶部
        window.scrollTo({ top: 0, behavior: 'smooth' });
        // 若要定位到页面的h1标题，替换为下面代码：
        // const mainTitle = document.querySelector('h1');
        // if (mainTitle) mainTitle.scrollIntoView({ behavior: 'smooth' });
    }
});

2. 在conf.py中配置加载这个JS文件：

html_js_files = [
    'fix_scroll.js',
]

方法2：修改主题模板，移除toctree链接的锚点 #

如果使用的是Read the Docs这类主题，可通过自定义模板覆盖toctree的链接生成逻辑：

1. 在项目根目录创建_templates文件夹，新建toctree.html文件。
2. 复制原主题的toctree.html代码（可在主题的安装目录中找到），修改链接部分，确保生成的是不带锚点的页面URL。比如将包含锚点的{{ item.link|e }}替换为仅保留页面路径的格式。

方法3：调整Sphinx配置禁用toc自动锚点 #

部分主题支持通过配置关闭toc的锚点跳转，比如在conf.py中添加：

html_theme_options = {
    'toc_depth': 0,  # 或根据主题调整相关参数
    'navigation_with_keys': False
}

注：不同主题的配置参数不同，需参考所用主题的文档。

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