CONTRIBUTING.md 不会在 github 页面上呈现为网页答案

【问题标题】：CONTRIBUTING.md does not render as a web page on github pagesCONTRIBUTING.md 不会在 github 页面上呈现为网页
【发布时间】：2017-08-27 06:40:23
【问题描述】：

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

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

然而，

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

返回 404，同时简单地添加 .md 扩展名

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

将页面作为降价源返回

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

【问题讨论】：

您可以添加指向您的 Github 存储库的直接链接吗？
另外，您能否指定您使用的是/docs 文件夹还是gh-pages 分支？
阅读时我怎么错过了那部分？ ??????
我认为页面构建过程中可能存在问题。
@ZacharyEspiritu github 项目是github.com/jtablesaw/tablesaw，contributing.md 文件位于 docs/ 文件夹中。

标签： github github-pages

【解决方案1】：

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

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

你必须修改_config.yml如下：

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

Here是github的相关帮助页面。

【讨论】：

对于较新的版本，这些现在必须放在一个数组中 include: [ 'CONTRIBUTING.md', 'LICENSE.md' ]

【解决方案2】：

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

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

另一方面，尽管 README.md 也是 Github 关键字文件，但看起来 Github Pages 支持使用名称为 README.md 的文件，因为它故意将它们解释为与 index.md 或 @ 相同的方式987654338@ 文件。请参阅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̶.̶

编辑：@Master_ex 正确地指出，您可以在 _config.yml 文件中使用 include configuration option 来包含通常会被 Github 排除的文件：

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

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

【讨论】：