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

Question

我正在将贡献.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

返回页面作为 Markdown 源

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

Answer 1

在 fork你的 repo，玩了一下它，并把我的头撞在墙上，因为我不明白为什么它不起作用之后，我意识到了一些事情：

\n\n

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

\n\n

\n
• CONTRIBUTING.md
\n
• ISSUE_TEMPLATE.md
\n
• PULL_REQUEST_TEMPLATE.md
\n
• ISSUE_AND_PULL_REQUEST_TEMPLATE.md
\n
• CODEOWNERS.md
\n

\n\n

另一方面，尽管这README.md也是一个 Github 关键字文件，但看起来 Github Pages 支持使用具有该名称的文件，因为它故意将它们解释为与or文件README.md相同的方式。有关详细信息，请参阅Github 博客中的此链接。index.mdindex.html

\n\n\n\n

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

\n\n

U\xcc\xb6n\xcc\xb6f\xcc\xb6o\xcc\xb6r\xcc\xb6t\xcc\xb6u\xcc\xb6n\xcc\xb6a\xcc\xb6t\xcc\xb6e\xcc\xb6l\xcc\xb6y\ xcc\xb6,\xcc\xb6 \xcc\xb6a\xcc\xb6t\xcc\xb6 \xcc\xb6l\xcc\xb6e\xcc\xb6a\xcc\xb6s\xcc\xb6t\xcc\xb6 \xcc\xb6i\xcc \xb6n\xcc\xb6 \xcc\xb6t\xcc\xb6h\xcc\xb6e\xcc\xb6 \xcc\xb6p\xcc\xb6r\xcc\xb6e\xcc\xb6s\xcc\xb6e\xcc\xb6n\xcc\xb6t \xcc\xb6,\xcc\xb6\xcc\xb6t\xcc\xb6h\xcc\xb6e\xcc\xb6r\xcc\xb6e\xcc\xb6\'\xcc\xb6s\xcc\xb6\xcc\xb6c\xcc\ xb6u\xcc\xb6r\xcc\xb6r\xcc\xb6e\xcc\xb6n\xcc\xb6t\xcc\xb6l\xcc\xb6y\xcc\xb6\xcc\xb6n\xcc\xb6o\xcc\xb6\xcc\xb6w\ xcc\xb6a\xcc\xb6y\xcc\xb6\xcc\xb6t\xcc\xb6o\xcc\xb6\xcc\xb6k\xcc\xb6e\xcc\xb6e\xcc\xb6p\xcc\xb6\xcc\xb6i\xcc\ xb6t\xcc\xb6\xcc\xb6w\xcc\xb6i\xcc\xb6t\xcc\xb6h\xcc\xb6\xcc\xb6t\xcc\xb6h\xcc\xb6e\xcc\xb6\xcc\xb6s\xcc\xb6a\ xcc\xb6m\xcc\xb6e\xcc\xb6\xcc\xb6f\xcc\xb6i\xcc\xb6l\xcc\xb6e\xcc\xb6\xcc\xb6n\xcc\xb6a\xcc\xb6m\xcc\xb6e\xcc\ xb6 \xcc\xb6a\xcc\xb6n\xcc\xb6d\xcc\xb6 \xcc\xb6h\xcc\xb6a\xcc\xb6v\xcc\xb6e\xcc\xb6\xcc\xb6G\xcc\xb6i\xcc\xb6t\ xcc\xb6h\xcc\xb6u\xcc\xb6b\xcc\xb6\xcc\xb6P\xcc\xb6a\xcc\xb6g\xcc\xb6e\xcc\xb6s\xcc\xb6\xcc\xb6b\xcc\xb6u\xcc\ xb6i\xcc\xb6l\xcc\xb6d\xcc\xb6\xcc\xb6a\xcc\xb6\xcc\xb6p\xcc\xb6a\xcc\xb6g\xcc\xb6e\xcc\xb6\xcc\xb6f\xcc\xb6o\ xcc\xb6r\xcc\xb6\xcc\xb6i\xcc\xb6t\xcc\xb6.\xcc\xb6

\n\n\n\n

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

\n\n

theme:   jekyll-theme-minimal\ninclude: contributing.md\n

\n\n

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

\n

Answer 2

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

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

您必须修改_config.yml如下：

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

这里是github的相关帮助页面。