How to store github wiki as part of the source

GitHub (and many git servers such as GitLab) offer project-level wikis where, as a rule, markdown files ( *.md ) are stored and generated ... well ... your project wiki.

It would be great if there was a way to save your wiki as part of the main source of the project, so when you make changes to your main project, your wiki also changes (well, if you made changes to your wiki markdown, which are).

Sort of:

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

Is there any way to do this? I see that wikis have cloned URLs and a number, which means they are treated as separate Git projects. Any way to combine the two?

+6
source share
2 answers

As mentioned in @larsks comments, you can use GitHub Pages for something like that. However, without any additional snap-ins, the documentation should be in a separate branch ("gh-pages") from your main project. However, there are several ways to combine them together, and some of the solutions can be used with other Git hosts with a little tweaking.

GPH import

The handy ghp-import tool actually takes the docs/ directory (or whatever directory you specify) and copies it to gh-pages for you (and you can click on GitHub). Since GitHub Pages uses Jekyll under the hood, if you have your docs/ files configured as a Jekyll project each time you run ghp-import , your documentation changes will be passed to the gh-pages branch. When these changes are migrated to GitHub, they launch Jekyll in Markdown files and refresh the site using the rendered HTML.

Of course, there are several problems with this solution. First of all, it is GitHub-specific, and secondly, it links the history of committing the `gh-pages' branch (see warning in the documentation).

git -subtree

Perhaps a more universal solution is to use git-subtree , which can copy (and save) the history of the subdirectory to a separate branch. It will copy only those commits that executed the specified subdirectory. In addition, any commits that include changes to both the specified subdirectory and other parts of your source include only changes to the subdirectory. I made a complete entry on how to use it using the GitHub pages a while ago.

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

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

Do not use github

If you do not want to use GitHub, you can (theoretically) use any of the above tools and configure another remote for the branch that contains only your documentation. Then, by copying your changes to the documentation branch (possibly using the git subtree split ), you can push this branch to the "wiki" repository of your host. I have not tried this personally. Your mileage may vary.

Do not use Jekyll

Even GitHub pages do not require you to use Jekyll to style your documents. If you click on the already rendered HTML on the GitHub pages, they will work just fine. Various static site generators ( more here ) offer this kind of functionality. For example, one popular MkDocs project will accept Markdown documents in your docs/ directory and display them in HTML. You can then upload these visualized documents to various hosting services.

This answer becomes dangerously close to recommendations for specific tools, so I will stop here.

+6
source

GitHub will display Markdown files in its viewer so you can do this efficiently without doing anything. If you put the link in your README.md as follows:

  ...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 the file will appear as Markdown in the viewport area.

+1
source

All Articles