How to store GitHub wiki as part of source

GitHub will render Markdown files in its viewer so you can effectively do this without doing anything. If you put a link in your README.md like so:

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

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


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.


Source

Every wiki provides an easy way to clone its contents down to your computer. You can clone the repository to your computer with the provided URL:

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

Once you have cloned the wiki, you can add new files, edit existing ones, and commit your changes. You and your collaborators can create branches when working on wikis, but only changes pushed to the master branch will be made live and available to your readers.