How do I edit my GitHub Wiki locally and include relative images?

This post sets out to describe how to edit a GitHub wiki on your computer as an alternative to editing directly within the GitHub web UI.

Cloning the GitHub Wiki to your computer

The wiki content is unsurprisingly stored within a Git repository and GitHub give you direct access to this repository which can enable you to edit the content locally on your computer. First though we need to clone the git repository to our computer.

• From your repository homepage on GitHub, click the Wiki link on the right hand side
• If you already have content in your wiki, Click the Clone URL button.

• If you have yet to create a page on your wiki you only see the green New Page button. Simply click New Page, set a page title (for example Home) and put some filler blurb content in the page body. Hit Save, and the Clone URL button should appear.

Hitting the Clone URL button will copy the git url for your wiki repository into your clipboard.

• Now, go to your favourite git client and clone the repository to your computer.

Editing your wiki content efficiently (Windows)

GitHub wiki content can be written in a number of different markup languages. My preference is markdown.

For this I use an awesome editor (if I do say so myself) called MarkPad which was one of the projects we worked on as part of the Code52 effort.

MarkPad is available for windows desktop (download) as well as a windows store app (install from Windows Store) – the source is also available for all if you want to have a poke about.

Sidenote: MarkPad is open source and as such is open to contributions from anyone. We are very open to community contributions so if you use it and think of a way to make it even better then please do get in touch via GitHub issues.

Instructions on how to write Markdown is out of the scope of this article but anyone familiar with editors such as MSWord will pick up thinks pretty quickly.

Ok, so one of the best life-hacks (read: makes your life simple) offered by MarkPad is its handling of images. You can of course construct links to images on the web in markdown but what is extra handy is that MarkPad can also generate image files on the fly from your clipboard.

Simply take a screenshot using something like Shotty (copy to clipboard) or Cropper (set output to clipboard)  and Paste (<ctrl>+v) the contents of your clipboard. MarkPad will automatically generate an image file appropriately named for where you pasted within your document (in relation to the closest header) and link to it in markdown. Very cool, very easy.

Note: When linking to images in markdown that have paths relative to the wiki page be sure to use  “\” as the path separator and not “/”

Push your changes to GitHub

Commit your changes, making sure to include (add) any new content and/or images generated then just perform a GIT push to submit your changes to github. Your changes will be visible on the wiki immediately – go marvel in their splendour.