使用mkdocs-static-i18n切换GitHub Pages首页语言时出现404错误

问题根源分析 #

你遇到的404问题确实是语言切换后的URL路径错误导致的：默认语言首页路径是something.github.io/some-page/（对应en/index.md），但切换法语时跳转到了something.github.io/fr/，而非正确的something.github.io/some-page/fr/，这说明链接配置或文档结构存在偏差。

具体解决方案 #

1. 修正文档目录结构 #

确保你的docs目录严格遵循folder结构要求，每个语言的首页都放在对应语言子文件夹下，且命名为index.md（不要改名，mkdocs默认识别该文件名作为页面入口）：

docs/
├── en/
│   ├── index.md       # 英文首页
│   └── other-pages.md # 其他英文页面
└── fr/
    ├── index.md       # 法语首页
    └── other-pages.md # 其他法语页面

2. 修复alternate链接配置 #

你当前的extra.alternate是硬编码的根路径，需要根据当前语言动态生成正确的链接路径。修改mkdocs.yml中的对应配置：

extra:
  alternate:
    # 从法语页面切换到英文首页
    - name: English
      link: "{{ '/' if i18n_locale == 'fr' else './' }}"
      lang: en
    # 从英文页面切换到法语首页
    - name: Français
      link: "{{ '/fr/' if i18n_locale == 'en' else './' }}"
      lang: fr

如果使用mkdocs-material主题，也可以去掉手动配置的extra.alternate，主题会基于i18n配置自动生成正确的语言切换链接。

3. 配置正确的site_url #

在mkdocs.yml中明确设置站点的完整URL，确保生成的链接路径正确：

site_url: https://something.github.io/some-page/

4. 本地验证构建结果 #

运行mkdocs build命令，查看生成的site目录结构，确认site/fr/index.html存在。如果不存在，检查：

• fr文件夹下是否有index.md文件
• i18n配置中fr的build字段是否为true

5. 恢复默认首页命名 #

不要将index.md改名为homepage，mkdocs默认以index.md作为每个目录的首页，改名会破坏默认的路径映射逻辑，导致基础链接无法重定向。

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