Terry : gollum

gollum -- A wiki built on top of Git

What is Gollum?

Gollum is a simple wiki system built on top of Git that powers GitHub Wikis. It is powered by Ruby and Sinatra framework.

Gollum wikis are simply Git repositories that adhere to a specific format. Gollum pages may be written in a variety of formats and can be edited in a number of ways depending on your needs. You can edit your wiki locally:

  • With your favorite text editor or IDE (changes will be visible after committing).
  • With the built-in web interface.
  • With the Gollum Ruby API.

Gollum follows the rules of Semantic Versioning and uses TomDoc for inline documentation.

System Requirements

System requirements for gollum

  • Python 2.5+ (2.7.3 recommended)
  • Ruby 1.8.7+ (1.9.3 recommended)
  • Unix like operating system (OS X, various Linux distributions)
  • Will not work on Windows (because of grit)


The best way to install Gollum is with RubyGems

gem install gollum

If you're installing from source, you can use Bundler to pick up all the gems

bundle install

In order to use the various formats that Gollum supports, you will need to separately install the necessary dependencies for each format. You only need to install the dependencies for the formats that you plan to use.

  • ASCIIDoc -- brew install asciidoc on mac or apt-get install -y asciidoc on Ubuntu
  • Creole -- gem install creole
  • Markdown -- gem install redcarpet
  • GitHub Flavored Markdown -- gem install github-markdown
  • Org -- gem install org-ruby
  • Pod -- Pod::Simple::HTML comes with Perl >= 5.10. Lower versions should install Pod::Simple from CPAN.
  • RDoc
  • ReStructuredText -- easy_install docutils
  • Textile -- gem install RedCloth
  • MediaWiki -- gem install wikicloth


Initialize a git repository, for example

mkdir ~/wiki
cd ~/wiki
git init

To view and edit your Gollum repository locally via the built in web interface, simply install the Gollum gem, navigate to your repository via the command line, and run the executable

cd ~/wiki

This will start up a web server running the Gollum frontend and you can view and edit your wiki at http://localhost:4567. To get help on the command line utility, you can run it like so

gollum --help

Note that the gollum server will not run on Windows because of an issue with posix-spawn (which is used by Grit).




You can also run gollum with any rack-compatible server by placing this config.ru file inside your wiki repository. This allows you to utilize any Rack middleware like Rack::Auth, OmniAuth, etc.

#!/usr/bin/env ruby
require 'rubygems'
require 'gollum/app'
gollum_path = File.expand_path(File.dirname(__FILE__)) # CHANGE THIS TO POINT TO YOUR OWN WIKI REPO
Precious::App.set(:gollum_path, gollum_path)
Precious::App.set(:default_markup, :markdown) # set your favorite markup language
Precious::App.set(:wiki_options, {:universal_toc => false})
run Precious::App

Your Rack middleware can pass author details to Gollum in a Hash in the session under the 'gollum.author' key.

Config File

Gollum optionally takes a --config file. See config.rb for an example.

Repository Structure

A Gollum repository's contents are designed to be human editable. Page content is written in page files and may be organized into directories any way you choose. Special footers can be created in footer files. Other content (images, PDFs, etc) may also be present and organized in the same way.

Page Files

Page files may be written in any format supported by GitHub-Markup (except roff). The current list of formats and allowed extensions is

  • ASCIIDoc: .asciidoc
  • Creole: .creole
  • Markdown: .markdown, .mdown, .mkdn, .mkd, .md
  • Org Mode: .org
  • Pod: .pod
  • RDoc: .rdoc
  • ReStructuredText: .rest.txt, .rst.txt, .rest, .rst
  • Textile: .textile
  • MediaWiki: .mediawiki, .wiki

Gollum detects the page file format via the extension, so files must have one of the supported extensions in order to be converted.

Page file names may contain any printable UTF-8 character except space (U+0020) and forward slash (U+002F). If you commit a page file with any of these characters in the name it will not be accessible via the web interface.Even though page files may be placed in any directory, there is still only a single namespace for page names, so all page files should have globally unique names regardless of where they are located in the repository.The special page file Home.ext (where the extension is one of the supported formats) will be used as the entrance page to your wiki. If it is missing, an automatically generated table of contents will be shown instead.

Building The Gem from master

$ gem uninstall -aIx gollum
$ git clone https://github.com/github/gollum.git
$ cd gollum
gollum$ rake build
gollum$ gem install --no-ri --no-rdoc pkg/gollum*.gem