如何在 GitHub Pages 上同时发布 Sphinx 生成的文档和 Markdown？答案

【问题标题】：How to publish both Sphinx generated docs and Markdown on GitHub Pages at the same time?如何在 GitHub Pages 上同时发布 Sphinx 生成的文档和 Markdown？
【发布时间】：2020-02-10 01:01:51
【问题描述】：

我想在同一个 GitHub Pages 项目中发布 Sphinx 为 Python 项目生成的文档和 Markdown 内容。

由于 Sphinx 文档包含以下划线开头的文件夹，例如 _static，而 Jekyll 将这些文件夹视为特殊文件夹，因此一般建议似乎很简单地将 .nojekyll 文件放入 GitHub Pages 根目录。

不幸的是，我还想发布一些用 Markdown 编写的内容，需要 Jekyll 正确呈现。

我们的想法是将 Sphinx 文档放在名为 docs 的子文件夹中，并将 Markdown 内容放在根文件夹中。大致是这样的：

root-+-docs-+-_static--+--...
     |      +-_sources-+--...
     +-somefile.md

使用.nojekyll 不是一个选项，因为那样somefile.md 将不会被渲染。

在我看来，我应该能够使用include directive 解决这个问题。

强制在转换中包含目录和/或文件。 .htaccess 是一个很好的例子，因为默认情况下会排除点文件。

所以我尝试了以下_config.yml（放在根文件夹中）：

github: [metadata]
encoding: UTF-8
kramdown:
    input: GFM
    hard_wrap: false
    toc_levels: 1..3
future: true
jailed: false
theme: jekyll-theme-cayman
gfm_quirks: paragraph_end
include: ['docs/_static/','docs/_sources/','docs/_modules/']

不幸的是，当尝试从 docs/_static/ 加载任何内容时，此配置仍会导致 404。

我怎样才能让它工作？

【问题讨论】：

标签： jekyll github-pages python-sphinx

【解决方案1】：

最简单的解决方案似乎是简单地使用两个 GitHub 存储库：

一个用于 Sphinx（带有 .nojekyll）
一个用于 Markdown 内容

【讨论】：