如何将GitHub wiki存储为源代码的一部分

Question

GitHub(以及许多git服务器,如GitLab)提供项目级wiki,通常,markdown(*.md)文件存储并形成......以及......项目的wiki.

这将是太酷了,如果有你的维基存储为主要项目源的一部分的方式,所以,当你更改推送到您的主项目,你的维基改变,以及(当然,如果你更改了维基降价文件那是).

就像是:

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

有没有办法实现这个目标？我看到wiki有克隆URL和数字,这意味着它们被视为单独的Git项目.有什么办法把两者结合起来？

Answer 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'分支的提交历史(参见文档中的警告).

git的子树

也许更通用的解决方案是使用git-subtree,它可以将子目录的历史记录复制(并保存)到单独的分支.它只会复制影响指定子目录的提交.此外,任何包含指定子目录和源的其他部分中的更改的提交仅包括对子目录的更改.我做了一篇关于如何在 GitHub页面上使用它的完整文章.

排序版本是在您想要更新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页面,它们将正常工作.各种静态站点生成器(这里更多)提供这种功能.例如,一个受欢迎的项目MkDocs将在您的docs/目录中获取Markdown文档并将它们呈现为HTML.然后,您可以将这些呈现的文档上载到各种托管服务.

这个答案非常接近推荐特定工具,所以我会在这里停下来.

Answer 2

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

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

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

Answer 3

来源

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

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

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