CONTRIBUTING.md 未在 github 页面上呈现为网页

Question

我正在将我的 contributing.md 文件从项目根目录移动到 docs/ 目录，以便它可以与文档的其余部分一起使用。在 github 页面中查看时，文档中的其他降价文件可以正确呈现。例如页面

https://jtablesaw.github.io/tablesaw/userguide/toc 按预期呈现页面 toc.md。

然而，

https://jtablesaw.github.io/tablesaw/contributing

returns 一个 404，同时简单地添加 .md 扩展

https://jtablesaw.github.io/tablesaw/contributing.md

returns 作为降价源的页面

github 项目是 https://github.com/jtablesaw/tablesaw。 contributing.md 文件位于 docs/ 文件夹中。

Answer 1

分叉 your repo 之后，玩了一会儿，然后因为不明白为什么它不起作用而用头撞墙，我意识到了一些事情：

Github Pages 不支持从具有 Github 可识别的其他用途名称的文件构建 Jekyll 页面。 这些文件名包括（在除了他们的小写版本）：

另一方面，尽管 README.md 也是一个 Github 关键字文件，但看起来 Github Pages 支持使用名称为 README.md 的文件，因为它故意将它们解释为与 index.md 或 index.html 文件相同的方式。有关详细信息，请参阅 this link from the Github blog。

要回答有关如何让文件显示在 /tablesaw/contributing 路径的具体问题，您可以重命名它并将其移动到 /docs/contributing/index.md 或 /docs/contributing/README.md 路径。

U̶n̶f̶o̶r̶t̶u̶n̶a̶t̶e̶l̶y̶,̶ ̶a̶t̶ ̶l̶e̶a̶s̶t̶ ̶i̶n̶ ̶t̶h̶e̶ ̶p̶r̶e̶s̶e̶n̶t̶,̶ ̶t̶h̶e̶r̶e̶'̶s̶ ̶c̶u̶r̶r̶e̶n̶t̶l̶y̶ ̶n̶o̶ ̶w̶a̶y̶ ̶t̶o̶ ̶k̶e̶e̶p̶ ̶i̶t̶ ̶w̶i̶t̶h̶ ̶t̶h̶e̶ ̶s̶a̶m̶e̶ ̶f̶i̶l̶e̶ ̶n̶a̶m̶e̶ ̶a̶n̶d̶ ̶h̶a̶v̶e̶ ̶G̶i̶t̶h̶u̶b̶ ̶P̶a̶g̶e̶s̶ ̶b̶u̶i̶l̶d̶ ̶a̶ ̶p̶a̶g̶e̶ ̶f̶o̶r̶ ̶i̶t̶.̶

编辑： notes correctly that you can use the include configuration option 在 _config.yml 文件中以包含通常被 Github:

排除的文件

theme:   jekyll-theme-minimal
include: contributing.md

参考原始示例，这将允许 Github 页面在 /docs/contributing 路径成功构建页面。

Answer 2

Zachary 的回答是正确的，但有一种方法可以修改 jekyll 的配置以包含特定页面。

这是一个例子：https://masterex.github.io/test-docs/contributing

您必须修改_config.yml如下：

theme: jekyll-theme-minimal
include: contributing.md

Here 是 github 的相关帮助页面。

CONTRIBUTING.md 未在 github 页面上呈现为网页

CONTRIBUTING.md does not render as a web page on github pages

github

github-pages