ReadTheDocs页面正确引用方式：路径是否需要添加.html后缀

为什么带.html后缀的链接现在无法访问 #

你使用的mkdocs默认开启了use_directory_urls配置项：

• 开启该配置时，mkdocs会将每个xxx.md文档编译为xxx/index.html文件，部署后访问路径为/xxx/，服务端会自动匹配目录下的index.html文件返回内容，这就是你现在不带.html后缀的链接可以正常访问的原因
• 关闭该配置时，mkdocs会直接将xxx.md编译为xxx.html文件，需要带.html后缀才能访问

你之前可以用带.html的链接访问，大概率是之前的构建环境中use_directory_urls被设置为false，后续因为mkdocs版本升级、配置文件重置、ReadTheDocs构建环境更新等原因，恢复到了默认开启的状态，所以旧的带.html后缀的链接就失效了。

为什么其他项目的链接可以带.html后缀 #

其他项目的文档大概率是以下两种情况：

• 用Sphinx框架搭建文档，Sphinx默认生成带.html后缀的静态文件
• 同样用mkdocs，但手动在mkdocs.yml中将use_directory_urls设置为了false

正确配置方式 #

你可以根据自己的需求选择以下任意一种方案：

方案1：继续使用无后缀的简洁路径（mkdocs官方推荐） #

不需要修改任何配置，只需要将README和文档内部的所有链接统一替换为不带.html后缀、末尾带/的格式即可，符合当前默认构建逻辑，链接格式更简洁。

方案2：恢复带.html后缀的访问方式 #

在你项目的mkdocs.yml配置文件中添加如下配置：

use_directory_urls: false

提交配置文件后触发ReadTheDocs重新构建，就会生成带.html后缀的静态文件，之前的旧链接就可以正常访问了。

可选：两种路径同时兼容 #

如果需要同时兼容两种格式的链接，可以使用mkdocs-redirects插件配置重定向规则，将其中一种路径的请求重定向到另一种路径，避免出现404问题。

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