gollum - A git-based Wiki

Gollum is a simple wiki system built on top of Git. A Gollum Wiki is simply a git repository of a specific nature:

• A Gollum repository’s contents are human-editable text or markup files.
• Pages may be organized into directories any way you choose.
• Other content can also be included, for example images, PDFs and headers/footers for your pages.
• Gollum pages:
  • May be written in a variety of markups.
  • Can be edited with your favourite editor (changes will be visible after committing) or with the built-in web interface.
  • Can be displayed in all versions, reverted, etc.
• Gollum strives to be compatible with GitHub and GitLab wikis.
  • Just clone your GitHub/GitLab wiki and view and edit it locally!
• Gollum supports advanced functionality like:
  • Diagrams using Mermaid or PlantUML
  • BibTeX and Citation support
  • Annotations using CriticMarkup
  • Mathematics via KaTeX or MathJax
  • Macros
  • Redirects
  • RSS Feed of latest changes
  • …and more

See the wiki for extensive documentation, along with screenshots of Gollum’s features.

---

Table of Contents

• System Requirements
• Installation
  • As a Ruby Gem
  • Via Docker
  • As a Web Application Resource (Java)
• Markups
  • Markdown Flavors
• Running Gollum
  • Quick Start from Command Line
  • Running From Source
  • Running with Rack
  • Running with an Authentication Server
  • Running as a Service
• Environment
• Configuration
  • Command-Line Options
  • Config File
• Contributing

---

System Requirements

Gollum runs both on Unix-like systems and on Windows.

Gollum runs either using ‘normal’ Ruby (MRI) or JRuby (Ruby on the Java Virtual Machine). On Windows, Gollum runs only using JRuby (either from source, or prebuilt).

On MRI, Gollum uses the rugged git library, while on JRuby/Java it utilizes the rjgit and JGit libraries. See here for more info.

Installation

As a Ruby Gem

Ruby is best installed either via RVM or a package manager of choice. Then simply:

gem install gollum

Installation examples for individual systems can be seen here.

Via Docker

See here for instructions on how to run Gollum via Docker.

As a Web Application Resource (Java)

The latest Release of Gollum will always contain a downloadable gollum.war file that can be directly executed on any system with a working Java installation:

java -jar gollum.war -S gollum <your-gollum-arguments-here>

When using the .war, please be sure to pass absolute paths to your Gollum arguments.

Markups

Gollum allows using different markup languages on different wiki pages. It presently ships with support for the following markups:

• Markdown (see below for more information on Markdown flavors)
• RDoc

You can easily activate support for other markups by installing additional renderers (any that are supported by github-markup):

• AsciiDoc – gem install asciidoctor
• Creole – gem install creole
• MediaWiki – gem install wikicloth
• Org – gem install org-ruby
• Pod – requires Perl >= 5.10 (the perl command must be available on your command line)
  • Lower versions should install Pod::Simple from CPAN.
• ReStructuredText – requires python >= 3
  • Note that Gollum will also need you to install docutils for python
• Textile – gem install RedCloth

Markdown Flavors

By default, Gollum ships with the kramdown gem to render Markdown. However, you can use any Markdown renderer supported by github-markup. This includes CommonMark support via the commonmarker gem. The first installed renderer from the list will be used (e.g., redcarpet will NOT be used if github/markdown is installed). Just gem install the renderer of your choice.

See here for instructions on how to use custom rendering gems and set custom options.

Running Gollum

Quick Start from Command Line

1. Run: gollum /path/to/wiki where /path/to/wiki is an initialized Git repository.
2. Open http://localhost:4567 in your browser.

Running From Source

1. git clone https://github.com/gollum/gollum
2. cd gollum
3. bundle install (may require sudo depending on your Ruby setup)
4. bundle exec bin/gollum
5. Open http://localhost:4567 in your browser.

Running with Rack

Gollum can also be run with any rack-compatible web server. More on that over here.

Running with an Authentication Server

Gollum can also be run alongside a CAS (Central Authentication Service) SSO (single sign-on) server. With a bit of tweaking, this adds basic user-support to Gollum. To see an example and an explanation, navigate over here.

Running as a Service

Gollum can also be run as a service. More on that over here.

Environment

Gollum uses the environment variable APP_ENV primarily to control how the underlying Sinatra app behaves:

• development – reload the app on every request
• production – load the app only once

Configuration

Gollum comes with the command line options listed below. Note that there are some additional ‘minor’ options to tweak Gollum’s behaviour that do not have commandline options, but can be configured in config.rb.

Command-Line Options

Option	Arguments	Description
--host	[HOST]	Specify the hostname or IP address to listen on. Default: ‘0.0.0.0’. (Note: 0.0.0.0 allows remote access. For a personal Wiki, use 127.0.0.1.)
--port	[PORT]	Specify the port to bind Gollum with. Default: 4567.
--config	[FILE]	Specify path to Gollum’s configuration file.
--ref	[REF]	Specify the git branch to serve. Default: main (or master if main is not found).
--bare		Tell Gollum that the git repository should be treated as bare.
--adapter	[ADAPTER]	Launch Gollum using a specific git adapter. Default: rugged. (See Git Adapters for more info.)
--base-path	[PATH]	Specify the leading portion of all Gollum URLs (path info). Setting this to /wiki will make the wiki accessible under http://localhost:4567/wiki/. Default: /.
--page-file-dir	[PATH]	Specify the subdirectory for all pages. If set, Gollum will only serve pages from this directory and its subdirectories. Default: repository root.
--static, --no-static		Use static assets. Defaults to false in development/test, true in production/staging.
--assets	[PATH]	Set the path to look for static assets.
--css		Tell Gollum to inject custom CSS into each page. Uses custom.css from wiki root (must be committed).
--js		Tell Gollum to inject custom JS into each page. Uses custom.js from wiki root (must be committed).
--no-edit		Disable the feature of editing pages.
--allow-uploads	[MODE]	Enable file uploads. If set to dir, Gollum will store all uploads in the /uploads/ directory in repository root. If set to page, Gollum will store each upload at the currently edited page. (Files can be uploaded by dragging and dropping onto the editor’s text area.)
--math	[RENDERER]	Enable rendering of mathematical equations. Valid renderers: mathjax, katex. Default: katex. Add custom configuration for the renderer to math.config.js and commit it to the repo.
--critic-markup		Enable support for annotations using CriticMarkup.
--irb		Launch Gollum in “console mode”, with a predefined API.
--h1-title		Tell Gollum to use the first <h1> as page title.
--no-display-metadata		Do not render metadata tables in pages.
--user-icons	[MODE]	Tell Gollum to use specific user icons for history view. Can be set to gravatar, identicon or none. Default: none.
--template-dir	[PATH]	Specify custom mustache template directory. Only overrides templates that exist in this directory.
--template-page		Use _Template in root as a template for new pages. Must be committed.
--emoji		Parse and interpret emoji tags (e.g. :heart:) except when the leading colon is backslashed (e.g. \:heart:).
--lenient-tag-lookup		Internal links resolve case-insensitively, will treat spaces as hyphens, and will match the first page found with a certain filename, anywhere in the repository. Provides compatibility with Gollum 4.x.
--help		Display the list of options on the command line.
--version		Display the current version of Gollum.
--versions		Display the current version of Gollum and auxiliary gems.

Config File

When the --config option is used, certain inner parts of Gollum can be customized. This is used throughout our wiki for certain user-level alterations, among which customizing supported markups will probably stand out.

See here for documentation about settings configurable in config.rb.

All of the mentioned alterations and options work both for Gollum’s config file (config.rb) and Rack’s config file (config.ru).

Contributing

Please consider helping out! See CONTRIBUTING.md for information on how to submit issues, and how to start hacking on gollum.