Images in GitHub’s wikis

GitHub is the best place (known to me) for doing a not-too-much-demanding management or collaboration of not-too-big projects. It offers you (of course!) repository hosting, powered by simple, yet effective bug and issues management and wiki pages for help or guides for your project. And the only problem, that beginners usually face, is hosting images for that wikis. GitHub allows you to upload images to issues in issue tracker and does all the dirty work of hosting them for you. But, a bummer appears, when it comes to images in wikis, because Add image button in any wiki page editor allows you to enter URL only and there is no way to simply upload them to your wiki.

You can, of course store images inside main repo, but that isn't going to work, if you have main repo private and wiki public. Even for public projects this introduces a lot of mess, as often documentation and coding is done by separate people or teams. Hosting images on free hosting services for any kind of professional project isn't an option at all, because it looks... unprofessionally.

Well... the solution is already provided by GitHub, only not so obvious. You can host your images inside your wiki, because it is itself a repository, which you can clone just, as you do with main repo. Simply change reponame to reponame.wiki in your clone URL:

git clone git@github.com:username/reponame.wiki.git

and there you go (``). You can add images to that repository, push changes back to GitHub and then add images to wiki page. You can do this in GitHub editor or directly in Markdown code of wiki page, before pushing changes. Only remember to use direct linking, that uses blob/master in URL:

![](https://github.com/user/repo/blob/master/path/file.png)

to avoid any revision or branch problems.

Some other things and side matters:

1. Images can be added to wiki pages in original dimensions, using Markdown tag (![alt-text](url)) or resized to proper size, using HTML img tag.

2. If you would like to control over both (code in main repo and documentation in wiki repo) at once, you may consider adding wiki repo as a submodule of main repo. Both repositories will be updated in the same time, with single push, though both will be still hosted as separate repos.

3. If GitHub isn't an option, you may consider some alternatives for wikis in your project.

If entire idea of Git-backed wikis in GitHub is something new to you, then this article in GitHub Help might be a good start point for reading. It is over five years old, but still can provide you with some basics on this matter.

Leave a Reply