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)
Installation
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
Running
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 gollum
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).
URLs
http://localhost:4567/pages http://localhost:4567/fileview
Rack
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