markdown - 为什么有些静态站点生成器使用 README.md 而不是 index.md？

Question

为什么静态站点生成器会使用除 index.md 之外的任何内容作为站点的根页面？这看起来很自然，但例如 VuePress 和 GitHub 期望 README.md 代替。当我在另一个 SSG 上工作时，我试图理解其中的原因。

标签： markdown

Answer 1

为什么有些静态站点生成器使用 README.md 而不是 index.md？

因为存储库主机对 README 文件进行了特殊处理。例如，GitHub、Bitbucket、GitLab 等在用户浏览源文件时都会显示目录的 README 文件。在某些情况下，如果 README 不存在，主机站点甚至会抗议。

自然，自述文件的内容通常与在索引文件中找到的内容相同。而且，当然，用户不希望维护两个具有相同内容的单独文件。如果他们这样做，静态站点生成器需要在构建站点时排除自述文件。因此，用户要求，静态站点生成器添加使用 README 文件作为目录索引文件的选项。它使源文件更干净并保持干燥（不要重复自己）。

就个人而言，我自己从来不需要该功能（在浏览 GitHib 等上的源文件时，我对丢失的 README 漠不关心）。但是，作为 MkDocs（静态站点生成器）的开发人员之一，在我们添加它之前，这是最需要的功能之一。现在它存在了，我们什么也没听到。我们需要做的一项调整是确保如果索引文件也存在于同一目录中，则忽略 README 文件（显然，有些用户维护这两个文件，每个文件都有不同的内容——在这种情况下，自述文件通常不包含在构建的站点中；但是，这似乎是最罕见的用例）。