How to store GitHub wiki as part of source
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).
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?
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 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.