October 19 2011
Searching GitHub Wikis with Gollum
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.
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.
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.)
Next, symlink the project, so that Pow knows about it. (Any folder name is fine, but “wiki” is simpler.)
Finally, touch tmp/restart.txt to tell Pow to restart. (I’d add tmp/ to .gitignore as well.)
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.
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.
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:
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.