Sphinx如何避免在链接中不必要地携带index.html？

不用改文档结构的几种办法 #

1. 配置html_use_directory_uris（基础操作） #

直接在conf.py里加一行：

html_use_directory_uris = True

这个配置会让Sphinx对内部交叉引用自动生成目录形式的链接（比如把path/to/index.html变成path/to/），但注意它只处理内部引用，一些自动生成的导航或外部链接可能还会带index.html，可以搭配下面的方法补全。

2. 写个小扩展批量替换链接 #

如果上面的配置不够彻底，自己写个极简扩展搞定所有链接：

• 项目里新建fix_index_links.py文件，代码如下：

from sphinx.application import Sphinx

def fix_index_links(app, doctree, docname):
    from docutils.nodes import reference
    for node in doctree.traverse(reference):
        if 'refuri' in node.attributes:
            ref = node['refuri']
            # 处理两种情况：末尾是index.html或者/之后的index.html
            if ref.endswith('index.html'):
                # 替换成目录路径
                node['refuri'] = ref[:-10] + '/' if '/' in ref[:-10] else '/'

def setup(app: Sphinx):
    app.connect('doctree-resolved', fix_index_links)

• 然后在conf.py的extensions列表里加上这个扩展：

extensions = [
    # 你原来的其他扩展...
    'fix_index_links'
]

这个扩展会在文档生成前遍历所有链接，把带index.html的都换成干净的目录路径，完全不用动现有文档结构。

3. 配合服务器配置兜底 #

如果上面的代码还是有漏网之鱼，服务器端补一刀：

• 不管是Apache还是Nginx，默认都支持访问目录时自动加载index.html，只要确保服务器配置里没禁用这个规则就行。
• 比如Nginx里默认有index index.html;的配置，Apache也有DirectoryIndex index.html，开启这个后，就算有链接指向index.html，用户访问时地址栏会自动变成目录路径，体验上一样干净。

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