October 19 2011

Searching GitHub Wikis with Gollum

by Brian Dunagan

Over a year ago, GitHub updated their wiki system to be powered by git. It was an awesome upgrade. Now I can check out a wiki, just like source code, and edit it in TextMate, just like source code. Really, really nice…except I can’t search.

Luckily, GitHub released Gollum. Gollum is a local version of their wiki software, wrapped up in a Ruby gem. It supports the same interactions that you get on a GitHub wiki. And, it supports search.

To set up Gollum, just open Terminal and follow the instructions below, using @mojombo’s jekyll as an example project.

# Install the gem. I'm using 1.3.1 with Ruby 1.9.2 (290).
gem install gollum

# Go to a GitHub wiki checkout.
git clone git://github.com/mojombo/jekyll.wiki.git wiki

# Install RedCloth to handle Jekyll's Textfile format.
gem install RedCloth

# Start Gollum.
cd path/to/wiki
gollum

Gollum is now running at http://localhost:4567/. You should see the search bar at the top. Here are two screenshots comparing Gollum to GitHub:

Still, remembering to run gollum and open localhost:4567 is a bit of a pain.

Enter Pow

With 37 Signals’ Pow web server, you always reach your wiki locally at http://wiki.dev/. Pow is ridiculously nice for keeping long-running Rails and Rack process running in the background. After I installed Pow using their awesome one-line instructions (curl get.pow.cx | sh), I used these instructions to integrate Gollum:

First, add config.ru to the base of your wiki repo with the following text. (Use the jekyll wiki repo from above. No need to commit the file. Just add it to .gitignore.)

# Copied from bin/gollum
require "gollum/frontend/app"

Precious::App.set(:gollum_path, File.dirname(__FILE__))
Precious::App.set(:wiki_options, {})
run Precious::App

Next, symlink the project, so that Pow knows about it. (Any folder name is fine, but “wiki” is simpler.)

cd ~/.pow
ln -s path/to/jekyll/ wiki

Finally, touch tmp/restart.txt to tell Pow to restart. (I’d add tmp/ to .gitignore as well.)

cd path/to/jekyll/wiki
mkdir tmp
touch tmp/restart.txt

Contrary to the linked post, I didn’t need to add anything to /etc/hosts. Pow just worked. Gollum 1.3.1 is fine, despite the comments in this ServerFault post. Just open http://wiki.dev.

Add a sidebar

A brilliant addition to Gollum is sidebar support. I committed _Sidebar.mediawiki to the wiki repo, and Gollum began displaying it next to each page. The sidebar is a really easy way to add a set of useful links to all pages.

Only commits count

Keep in mind that if changes aren’t committed, Gollum doesn’t see them. For example, I added _Sidebar.mediawiki to the repo folder and refreshed the browser page. No sidebar. Took me a bit to realize Gollum still didn’t see it. You have to commit changes for them to exist to Gollum.

HTML sanitization

GitHub spells this out in its gollum readme, but it’s worth reiterating. Gollum sanitizes the input with @rgrove’s sanitize gem, removing any malformed HTML or security issues like custom CSS. This sanitization converts red into red.

To change that setting locally, just find lib/gollum/sanitization.rb and add ‘style’ to the end of the ATTRIBUTES list. Your local version will use the custom CSS, and the GitHub version will silently strip it out.

MediaWiki supported

I switched to a GitHub wiki from a MediaWiki instance. Converting was easy: click Edit for each page, save the contents as Page.mediawiki, repeat, push to GitHub. Done.

GitHub is able to render MediaWiki markup due to @nricciar’s handy WikiCloth Ruby gem. The latest release is 0.7.0, but it has a couple issues. I submitted a couple fixes in a pull request today, and @nricciar already merged them into master. To use the latest WikiCloth sources as a gem for Gollum, follow these steps:

# Remove existing version.
gem uninstall wikicloth

# Fetch the sources from GitHub.
git clone git://github.com/nricciar/wikicloth.git

# Build master and install that gem.
cd wikicloth
gem build wikicloth.gemspec
gem install wikicloth-0.7.0.gem

# Restart Gollum with Pow.
cd path/to/wiki
touch tmp/restart.txt

GitHub Wiki Search

Of course, GitHub will add searching on the website eventually. They’re prodigious coders, and Issues already has search. I’m sure they’re getting to it. Until then, just open http://wiki.dev/ and search.