011 · MkDocs 构建 README 与 index 冲突告警

问题现象

mkdocs build 告警 Excluding 'README.md' ... conflicts with 'index.md'。

排查过程

阅读 MkDocs 对同目录首页文件规则；确认根目录同时存在 README.md 与 index.md 时的排除行为。

根因

同一层级两个「入口」候选，Material/MkDocs 选择其一并排除另一个。

改进计划

明确 站点首页 为 index.md；若 README.md 需进站点则改名或移出该 docs_dir 根级。

经验教训

协作规范里写清 「站点根允许的首页文件名」，避免 Obsidian/Git 习惯与 MkDocs 冲突。