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

  • Shortest hash? MD5 / SHA . First chars, git
  • View website live after Git push
  • Using DVCS for an RDBMS audit trail
  • Gitolite bug when pushing to server
  • gitosis-admin git push failed, exec hooks/post-update
  • override git config --system in .gitconfig user file ( git config --global )
  • 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?

  • Git Conflict — Showing False Positive
  • How is a pathspec supposed to work?
  • difference between .gitmodules and specifying submodules in .git/config?
  • git, vimdiff and dirdiff
  • Signing commit with OpenPGP subkey fails
  • In git, how do you revert a file back to 3 commits ago?
  • 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.

    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.

    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.

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