How to store GitHub wiki as part of source

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).

  • How to delete an ORIG_HEAD branch in git?
  • Go, go get, go install, local packages, and version control
  • Creating pull requests in gitlab
  • VS2015 support for ssh protocol in git client
  • SSL certificate issue while creating git clone with TortoiseGit
  • I upgraded SVN::Core via CPAN and now git-svn doesn't recognise http:// URLs
  • Something like:


    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?

  • “Cannot update paths and switch to branch at the same time”
  • find difference between 2 remote branches
  • ansible: git module is hanging
  • How do I get TeamCity to automatically merge a Git feature branch with master and fail the build in case of merge conflicts?
  • Can vim diff use the patience algorithm?
  • How to get certain commit from GitHub project
  • 2 Solutions collect form web for “How to store GitHub wiki as part of source”

    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.


    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).


    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.

    GitHub will render Markdown files in its viewer so you can effectively do this without doing anything. If you put a link in your like so: see more info [click Here](docs/ So on and so forth

    then when someone clicks on the link in your, they will get to the right place and file will be rendered as Markdown in the viewer window area.

    Git Baby is a git and github fan, let's start git clone.