为什么 Github Pages 不提供我的文档？答案

【问题标题】：Why won't Github Pages serve my documentation?为什么 Github Pages 不提供我的文档？
【发布时间】：2020-02-25 00:30:48
【问题描述】：

我使用 sphinx 构建 html 文档，并且正在开源我公司的一些私人存储库。

在内部，我们通过 Cloudfront 从 S3 存储桶提供文档，因此我们可以将访问控制放在它前面。但对于开源，我认为通过 Github Pages 发布将是阻力最小的途径。

但是，我无法让服务正常工作。

Here is my repo，我的 index.html 在 /docs 文件夹中。

Here is the site，它没有应用任何链接的 css，并且所有页面链接都断开了。

我尝试通过仅使用已构建的文档创建 test repo 并从 master 发布来隔离问题。

As you can see，这个连index.html都没有尝试服务，我只是得到一个404页面。

这些文件既可以在本地工作，也可以在从 AWS 提供服务时工作，所以我有点不明白为什么 Github Pages 不能正确提供服务。我觉得我一定是在做某种愚蠢的疏忽。如果有更多经验的人可以看看并指出我的方式错误，我将不胜感激。我大部分时间都是后端工程师，所以网站逻辑有点超出我的正常驾驶室。提前致谢！

【问题讨论】：

【解决方案1】：

对于遇到同样事情的其他人，我想通了。因为我在 CI/CD 管道中预先构建了站点，所以我不需要 jekyll 来为我构建站点，并且需要为其添加一个空的配置文件。

接下来，您设置 .nojekyll 文件以表明您没有使用 Jekyll 作为您在此存储库中的静态站点生成器。

感谢您的帮助！

【讨论】：

【解决方案2】：

您需要一个_config.yml，并且您需要在 Master 上为 repo 启用 github 页面（转到设置）。之后，你还需要一个 Gemfile 如下：

source 'https://rubygems.org'

gem 'github-pages'

通常情况下，GitHub 页面站点需要位于根目录中，而您的看起来像是在 /docs 文件夹中，所以我相信您可以通过 Google 搜索如何做到这一点。虽然使用 GH 页面可能无法实现，但我不确定。

如果它必须是一个子文件夹而不是项目的根目录，也许这样的东西会起作用：https://gist.github.com/cobyism/4730490

这是我的_config: 中用于准系统网站的内容：

permalink: pretty
sass:
  sass_dir: _scss
  style: compressed

我确定你可以离开sass

【讨论】：

感谢您的回复。 Github Pages 有一个“从 master/docs 发布”选项，它应该是针对这个用例的。我会看看是否添加了配置和 gemfile 帮助。在他们的概述中根本没有提到这很奇怪。
让我至少添加配置中的内容
我想通了。我需要在“/docs”目录中添加一个空白的“.nojekyll”文件。由于我正在预先构建站点并且只需要提供服务，因此 jekyll 构建将其搞砸了。感谢您的帮助。
加到顶级答案了，不过两天接受不了自己的答案哈哈。哦，好吧。