【问题标题】：How to store GitHub wiki as part of source如何将 GitHub wiki 存储为源代码的一部分
【发布时间】：2015-11-05 08:05:35
【问题描述】：

GitHub（以及许多 git 服务器，例如 GitLab）提供项目级 wiki，通常在其中存储 markdown (*.md) 文件并形成......嗯......您项目的 wiki。

如果有办法将您的 wiki 存储为主项目源的一部分，那将是太酷，这样当您将更改推送到主项目时，您的 wiki 也会更改（以及，如果您对 wiki markdown 文件进行了更改，则）。

类似：

myproject/
    src/main/resources/
    src/main/groovy/
    build.grade
    docs/
        Home.md
        About_This_Project.md
        etc.

有没有办法做到这一点？我看到 wiki 具有克隆 URL，并且认为这意味着它们被视为单独的 Git 项目。有什么办法可以将两者结合起来？

【问题讨论】：

你不能在 wiki 上这样做，但你可以使用 Github pages 来做类似的事情。
请注意，html 也会在 github 上正确显示。我看到很多项目都有从自述文件到项目帮助/wiki 的 index.html 页面的链接。
这个问题与How to integrate a GitHub wiki into the main project重复

标签： git github markdown wiki

【解决方案1】：

正如@larsks 在评论中提到的那样，您可以使用GitHub Pages 进行类似的操作。但是，如果没有一些额外的工具，文档将需要位于主项目的单独分支（“gh-pages”）中。但是，有几种方法可以将两者融合在一起，并且一些解决方案只需稍作调整即可与其他 Git 主机一起使用。

gph 导入

方便的工具ghp-import 实际上获取docs/ 目录（或您指向的任何目录）并将其复制到 gh-pages 分支中（并且可以选择推送到 GitHub）。由于 GitHub Pages 在后台使用 Jekyll，如果您将 docs/ 中的文件配置为 Jekyll 项目，则无论何时运行 ghp-import 命令，您对文档的更改都将提交到 'gh-pages ' 分支。当这些更改被推送到 GitHub 时，它们会在 Markdown 文件上运行 Jekyll，并使用呈现的 HTML 更新站点。

当然，此解决方案存在一些问题。首先，它是 GitHub 特有的，其次，它管理 `gh-pages' 分支的提交历史记录（参见文档中的warning）。

git 子树

也许更通用的解决方案是使用git-subtree，它可以将子目录的历史复制（并保留）到单独的分支。它只会复制影响指定子目录的提交。此外，在指定子目录和源的其他部分中包含更改的任何提交仅包括对子目录的更改。不久前，我使用 GitHub Pages 在 how to use it 上写了一篇完整的文章。

排序版本是在您想要更新gh-pages 分支（或您正在使用的任何分支）的任何时候从您的主分支运行以下命令：

git subtree split --branch gh-pages --prefix docs/
git push origin gh-pages

不使用 GitHub

如果您不想使用 GitHub，您可以（理论上）使用上述任一工具，并为仅包含您的文档的分支设置不同的远程。然后，在将您的更改复制到文档分支（可能使用git subtree split 命令）之后，您可以将该分支推送到主机的“wiki”存储库。我没有亲自尝试过。您的里程可能会有所不同。

不使用 Jekyll

即使是 GitHub Pages 也不需要您使用 Jekyll 来呈现您的文档。如果你将已经渲染的 HTML 推送到 GitHub Pages，它们就可以正常工作。各种static site generators (more here) 提供这种功能。例如，一个流行的项目MkDocs 将获取docs/ 目录中的Markdown 文档并将它们呈现为HTML。然后，您可以将这些呈现的文档上传到各种托管服务。

这个答案已经非常接近推荐特定工具了，所以我会在这里停下来。

【讨论】：

【解决方案2】：

Source

每个 wiki 都提供了一种将其内容复制到您的计算机的简单方法。您可以使用提供的 URL 将存储库克隆到您的计算机：

$ git clone https://github.com/YOUR_USERNAME/YOUR_REPOSITORY.wiki.git

克隆 wiki 后，您可以添加新文件、编辑现有文件并提交更改。您和您的协作者在处理 wiki 时可以创建分支，但只有推送到主分支的更改才会生效并可供您的读者使用。

【讨论】：

【解决方案3】：

GitHub 将在其查看器中呈现 Markdown 文件，因此您无需执行任何操作即可有效地执行此操作。如果您像这样在 README.md 中添加链接：

 ...to see more info [click Here](docs/SomeFile.md). So on and so forth

然后当有人点击您的 README.md 中的链接时，他们将到达正确的位置，文件将在查看器窗口区域中呈现为 Markdown。

【讨论】：