GitHub（以及许多git服务器（例如 GitLab）提供项目级 wiki，其中通常包含 markdown（*.md）文件被存储并形成......好吧......你的项目的wiki。

这将是so cool如果有一种方法可以将您的 wiki 存储为主项目源代码的一部分，这样当您将更改推送到主项目时，您的 wiki 也会随之更改（当然，如果您对 wiki markdown 文件进行了更改）。

就像是：

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

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

正如@larsks 在评论中提到的，您可以使用GitHub 页面 https://pages.github.com/对于这样的事情。但是，如果没有一些额外的工具，文档将需要位于主项目的单独分支（“gh-pages”）中。然而，有几种方法可以将两者融合在一起，并且一些解决方案只需稍加调整即可与其他 Git 主机一起使用。

gph-导入

方便的工具ghp 导入 http://jekyllrb.com/实际上需要docs/目录（或您指向的任何目录）并将其复制到 gh-pages 分支（并且可以选择推送到 GitHub）。正如 GitHub Pages 使用的Jekyll https://en.wikipedia.org/wiki/Jekyll_%28software%29在幕后，如果你有你的文件docs/配置为 Jekyll 项目，任何时候运行ghp-import命令，您对文档的更改将提交到“gh-pages”分支。当这些更改被推送到 GitHub 时，他们会在 Markdown 文件上运行 Jekyll，并使用渲染的 HTML 更新网站。

当然，这个解决方案存在一些问题。首先，它是 GitHub 特定的，其次，它管理“gh-pages”分支的提交历史记录（请参阅warning https://github.com/davisp/ghp-import#big-fat-warning在文档中）。

git 子树

也许更通用的解决方案是使用git 子树 https://github.com/apenwarr/git-subtree，它可以将子目录的历史记录复制（并保留）到单独的分支。它只会复制影响指定子目录的提交。此外，任何包含指定子目录和源代码其他部分中的更改的提交仅包含对子目录的更改。我写了一篇完整的文章如何使用它 https://gist.github.com/waylan/4505033不久前使用 GitHub Pages。

排序版本是在您想要更新时从 master 分支运行以下命令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，它们将正常工作。各种各样的静态站点生成器 https://www.staticgen.com/ (更多这里 https://staticsitegenerators.net/）提供这种功能。例如，一个流行的项目，MkDocs http://www.mkdocs.org/，将把 Markdown 文档放在你的docs/dir 并将它们渲染为 HTML。然后，您可以将这些渲染的文档上传到各种托管服务。

这个答案已经非常接近推荐特定工具了，所以我就到此为止。