How To Use GitHub Wikis For Collaborative Documentation

This week I've been updating the documentation for INN's Largo WordPress theme. The documentation previously lived on the project website but we're now adding a wiki attached to the INN/Largo repository on GitHub.

In this post I'll use the Largo wiki as an example to show you how to setup a Github wiki for your project.

Setup

GitHub wikis are themselves git repositories.1 This means you can keep track of changes to the wiki and accept issues and pull requests to a repository made to contain the wiki.

To allow contributors outside of our team to submit pull requests and issues to the wiki, it makes sense to set it up as a separate repository. When the project updates, we'll push updates from the wiki repository to the wiki on the main repository for the project.

For our purposes, the container repository for the wiki is called Largo-docs.

These are the remotes I have for Largo-docs:

$ git remote -v
origin	git@github.com:INN/Largo-docs.git (fetch)
origin	git@github.com:INN/Largo-docs.git (push)
wiki	git@github.com:INN/Largo.wiki.git (fetch)
wiki	git@github.com:INN/Largo.wiki.git (push)

The first remote there, origin, is the container repository for the wiki content (Largo-docs). The second is the wiki that's attached to the main Largo theme repo.

On GitHub, the URIs for project wikis insert .wiki between projectname and .git.

GitHub project wikis are ‘magical’ repositories that are associated with your project, but are not part of the project repository. When you push to them, the wiki is rebuilt with the new content automatically. If you use GitHub pages, it’s very similar.

Since Largo-docs is just another GitHub repository, you can provide users a link to the repository’s issues page, where they can give you suggestions and pull requests. If you want to allow people to contribute to the wiki without allowing people to directly edit the wiki, this is the way to do it.

When it comes time to publish new content to the wiki associated with the main theme repository, I make sure I'm on the master branch of the Largo-docs repository and then I push to the remote I set up for the wiki on the main Largo repository.

It's as simple as:

git checkout origin/master
git push -u wiki master

Organizing the Wiki Repository

Keeping the wiki in a separate repository also makes organization easier.

By default, GitHub wikis are flat, with no hierarchy. Inside a repository, you can create folders and place individual wiki pages in them.

screenshot

These pages are simply separate files, where the filename becomes the page name. For example, example-filename_here.md becomes “example filename_here” - use capitalization and dashes to create proper article titles.

The folder structure isn't reflected when GitHub generates the wiki, but it's great for your own organization.

If you want to structure the wiki, with some posts being parents to others, you can create a table of contents for the wiki and put it in a file named _Sidebar.md. The underscore is important.

screenshot-2

Create the hierarchy with an ordered or unordered list, and use horizontal rules as separators. Within posts, use Gollum syntax to link between pages.

Authoring and Editing

GitHub doesn't use straight Markdown for wikis, though. Wikis can use nine different markup languages for posts, with Gollum syntax used for internal links and images.

Mixing Gollum and Markdown markup leads to some interesting formatting, but nothing deal-breaking. In the container repository, GitHub will only render GitHub-Flavored Markdown (GFM). The Gollum-style inter-page links and image links will be ignored, leading to situations like this in the container repo:

This is what happens when you mix Gollum link markup and Markdown in a page: GitHub only renders the Markdown.
This is what happens when you mix Gollum link markup and Markdown in a page: GitHub only renders the Markdown.

Not pretty, but hey, it works!

If you're looking to document your project in a way that others can contribute to, but you don't necessarily want to open wiki editing to everyone, this is a great way to do it!

And of course you're welcome to contribute and help improve our documentation at https://github.com/INN/Largo-docs.


1: So are GitHub Gists, incidentally. And since May 1, 2014, you can use GFM task lists in wikis.