如何將 GitHub wiki 存儲為源代碼的一部分

Question

GitHub（以及許多git服務器，例如 GitLab）提供項目級 wiki，其中通常存儲*.md ( *.md ) 文件並形成……嗯……您項目的 wiki。

它會如此冷靜，如果有你的維基存儲為主要項目源的一部分的方式，所以，當你更改推送到您的主項目，你的維基改變，以及（當然，如果你更改了維基降價文件那是）。

就像是：

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

有什么辦法可以做到這一點嗎？ 我看到維基有克隆 URL 和數字，這意味着它們被視為單獨的 Git 項目。 有沒有辦法將兩者結合起來？

Answer 1

正如@larsks 在評論中提到的，你可以使用GitHub Pages來做這樣的事情。 但是，如果沒有一些額外的工具，文檔將需要位於與主項目不同的分支（“gh-pages”）中。 但是，有幾種方法可以將兩者融合在一起，其中一些解決方案只需稍加調整即可與其他 Git 主機一起使用。

gph-導入

方便的工具ghp-import實際上獲取docs/目錄（或您指向的任何目錄）並將其復制到 gh-pages 分支為您（並且可以選擇推送到 GitHub）。 由於 GitHub Pages 在ghp-import使用Jekyll ，如果您將docs/中的docs/配置為 Jekyll 項目，則ghp-import運行ghp-import命令時，您對文檔的更改都將提交到“gh-pages”分支。 當這些更改被推送到 GitHub 時，它們會在 Markdown 文件上運行 Jekyll 並使用呈現的 HTML 更新站點。

當然，此解決方案存在一些問題。 首先，它是特定於 GitHub 的，其次，它保存了 `gh-pages' 分支的提交歷史（請參閱文檔中的警告）。

git子樹

也許更通用的解決方案是使用git-subtree ，它可以將子目錄的歷史記錄復制（並保留）到單獨的分支。 它只會復制影響指定子目錄的提交。 此外，任何包含指定子目錄和源其他部分更改的提交僅包含對子目錄的更改。 不久前，我寫了一篇關於如何在GitHub Pages 中使用它的完整文章。

排序版本是在您想要更新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，它們將正常工作。 各種靜態站點生成器（更多在這里）提供這種功能。 例如，一個流行的項目MkDocs將獲取docs/目錄中的 Markdown 文檔並將它們呈現為 HTML。 然后，您可以將這些呈現的文檔上傳到各種托管服務。

這個答案非常接近推薦特定工具，所以我會在這里停下來。

Answer 2

來源

每個 wiki 都提供了一種簡單的方法來將其內容克隆到您的計算機。 您可以使用提供的 URL 將存儲庫克隆到您的計算機：

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

克隆 Wiki 后，您可以添加新文件、編輯現有文件並提交更改。 您和您的合作者可以在 wiki 上工作時創建分支，但只有推送到主分支的更改才會生效並可供您的讀者使用。

Answer 3

GitHub 將在其查看器中呈現Markdown文件，因此您無需執行任何操作即可有效地執行此操作。 如果您在 README.md 中放置一個鏈接，如下所示：

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

然后，當有人單擊您 README.md 中的鏈接時，他們將到達正確的位置，並且文件將在查看器窗口區域中呈現為 Markdown。