如何将GitHub维基存储为源代码的一部分 [英] How to store GitHub wiki as part of source

问题描述

GitHub(以及许多git服务器，如GitLab)提供项目级Wiki，通常在其中存储标记(*.md)文件并形成……嗯……项目的Wiki。

如果有一种方法可以将Wiki存储为主项目源代码的一部分，以便在您将更改推送到主项目时，您的Wiki也会更改(如果您对Wiki标记文件进行了更改)，那么将会非常酷。

类似于：

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

有什么办法可以做到这一点吗？我看到维基有克隆的URL和图形，这意味着它们被当作单独的Git项目对待。有没有办法把这两者结合起来？

推荐答案

正如@larsks在评论中提到的，您可以使用GitHub Pages来做这样的事情。然而，如果没有一些额外的工具，文档将需要与您的主项目位于不同的分支("gh-page")中。但是，有几种方法可以将两者融合在一起，其中一些解决方案只需稍作调整即可用于其他Git主机。

gph-import

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

当然，此解决方案存在一些问题。首先，它是特定于GitHub的，其次，它包含"gh-ages"分支的提交历史记录(请参阅文档中的warning)。

git-subtree

也许更通用的解决方案是使用git-subtree，它可以将子目录的历史记录复制(并保留)到单独的分支。它将只复制影响指定子目录的提交。此外，在指定子目录和源代码的其他部分中都包含更改的任何提交都只包含对子目录的更改。前段时间我用GitHub页面对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页面也不需要使用Jekyll来呈现文档。如果您将已经呈现的HTML推送到GitHub页面，它们将工作得很好。各种static site generators(more here)都提供这种功能。例如，一个流行的项目MkDocs将获取docs/目录中的Markdown文档并将它们呈现为HTML。然后，您可以将这些呈现的文档上载到各种托管服务。

此答案即将推荐特定工具，因此我将到此为止。

这篇关于如何将GitHub维基存储为源代码的一部分的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！