How to store GitHub wiki as part of source

Question

GitHub (and many git servers such as GitLab) offer project-level wikis where, typically, markdown (*.md) files are stored and form...well...your project's wiki.

It would be so cool if there was a way to store your wiki as part of the main project source, so that when you push changes to your main project, your wiki changes as well (well, if you made changes to your wiki markdown files that is).

Something like:

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

Is there any way to accomplish this? I see that wikis have clone URLs and figure that means they get treated as separate Git projects. Any way to combine the two?

Answer 1

As mentioned by @larsks in a comment, you can use GitHub Pages for something like this. However, without some extra tooling, the documentation would need to be in a separate branch ("gh-pages") from your main project. However, there are a few ways to meld the two together and some of the solutions could be used with other Git hosts with a little tweaking.

gph-import

The handy tool ghp-import actually takes the docs/ directory (or whichever directory you point it to) and copies it over to the gh-pages branch for you (and can optionally push to GitHub). As GitHub Pages uses Jekyll under the hood, if you have your files in docs/ configured as a Jekyll project, any time you run the ghp-import command, your changes to the documentation will get committed to the 'gh-pages' branch. When those changes are pushed to GitHub, they run Jekyll on the Markdown files and update the site with the rendered HTML.

Of course, there are a few issues with this solution. First of all, it is GitHub-specific and secondly, it hoses the commit history of the `gh-pages' branch (see the warning in the documentation).

git-subtree

Perhaps a more universal solution is to use git-subtree, which can copy (and preserve) the history of a subdirectory to a separate branch. It will only copy the commits which effected the specified sub-directory. Additionally, any commits which included changes in both the specified subdirectory and other parts of your source only include the changes to the subdirectory. I did a full write-up on how to use it with GitHub Pages a while back.

The sort version is to run the following commands from your master branch anytime you want to update the gh-pages branch (or whichever branch you are using):

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

Not using GitHub

If you don't want to use GitHub, you could (theoretically) use either of the above tools, and set up a different remote for the branch which contains your documentation only. Then, after copying your changes into the documentation branch (perhaps using the git subtree split command), you could push that branch to the "wiki" repository of your host. I haven't tried this personally. Your mileage may vary.

Not using Jekyll

Even GitHub Pages does not require you to use Jekyll to render your documents. If you push already rendered HTML to GitHub Pages, they will work just fine. Various static site generators (more here) offer this sort of functionally. For example, one popular project, MkDocs, will take the Markdown documents in your docs/ dir and render them to HTML. You can then upload those rendered documents to various hosting services.

This answer is getting dangerously close to recommending specific tools, so I'll stop here.