Static Site Generator for Gollum Wikis
Ruby CSS JavaScript
Latest commit 94908f2 Apr 2, 2014 @dreverri Set url_path to cname
Failed to load latest commit information.
bin adding optional ability to preserve the original wiki directory struc… Jun 8, 2013
lib Set url_path to cname Apr 2, 2014
.gitignore Remove Gemfile.lock Apr 2, 2014
Gemfile Add rake dependency to Gemfile May 21, 2013 Updated URL for Liquid's wiki, due to repo having moved to Shopify's … May 8, 2012
Rakefile Porting static site generation to separate gem Oct 21, 2010
gollum-site.gemspec Include github-markdown as a development dependency so tests render m… Apr 2, 2014

gollum-site -- A static site generator for Gollum


Generates a static site from a Gollum Wiki.


The easiest way to install gollum-site is with RubyGems:

$ [sudo] gem install gollum-site

Supported formats

Gollum supports several formats for wiki text. In order to generate the various supported formats certain dependencies must be met:

  • ASCIIDoc -- brew install asciidoc
  • Creole -- gem install creole
  • Markdown -- gem install rdiscount
  • 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


Static sites can be generated using the executable provided:

   $ gollum-site generate

Once a site has been generated (output to "_site" by default) you can use the gollum-site executable to start a web server for the site:

   $ gollum-site serve

The executable provides a few options which are described in the help menu:

   $ gollum-site --help

Static Site Templates

The static site generator uses the Liquid templating system to render wiki pages. The generator looks for _Layout.html files to use as templates. Layouts affect all pages in their directory and any subdirectories that do not have a layout file of their own.

A layout is a Liquid template applied to a wiki page during static site generation with the following data made available to it:

  • wiki.base_path The base path of the Wiki to which the page belongs
  • page.path The output path of the page
  • page.content The formatted content of the page
  • page.title The title of the page
  • page.format The format of the page (textile, org, etc.)
  • The author of the last edit
  • The date of the last edit

A note about wiki.base_path

tl;dr - Don't use "." or "" as base paths. Use "./" if relative paths are required.

The application of base path differs between Gollum page links and the layout. Gollum uses File.join to combine the base path and the page link. The layout simply renders the base path provided by the user. This can result in differing URLs.

Scenario 1: Don't include a forward slash after wiki.base_path in layouts

base_path Gollum Link URL Layout Link URL
"." [[Page]] "./Page" "{{ wiki.base_path }}Page" ".Page"
"" [[Page]] "/Page" "{{ wiki.base_path }}Page" "Page"

Scenario 2: Include a forward slash after wiki.base_path in layouts

base_path Gollum Link URL Layout Link URL
"/" [[Page]] "/Page" "{{ wiki.base_path }}/Page" "//Page"

Considering scenario 2 breaks links when using the default base path it is advised to use scenario 1 and not use "." and "" as base paths. Use "./" if relative paths are required.


The gollum-site executable provides the ability to import the default layout to the current wiki. The import command will copy the required "_Layout.html", css and javascript to the current wiki. These files must be committed to the wiki repository before the 'generate' command will recognize them unless you use the "--working" option.

   $ gollum-site import


You can generate a static site from untracked/uncommitted changes by using the "--working" flag.

   $ gollum-site generate --working


When running the gollum-site server you can enable directory watching to update the static site when changes are made to any of the wiki or static files. This feature only works with the "serve" command.

   $ gollum-site serve --watch

This feature requires the directory_watcher gem.


You can customize sanitization with three options:

  • --allow_elements: custom elements allowed, comma separated
  • --allow_attributes: custom attributes allowed, comma separated
  • --allow_protocols: custom protocols in href allowed, comma separated

    $ gollum-site generate --allow_elements embed,object --allow_attributes src --allow_protocols irc

Ignore File

If there is a file named .gollumignore in the root of the repository, the exclusions it specifies will be used to suppress gollum-site generation accordingly. The .gollumignore file uses .gitignore semantics.


To see gollum-site in action, let's use it to generate a static site from a Gollum Wiki. For this example I will use the Radiant wiki:

   $ git clone git://
   $ cd
   $ gollum-site generate
   $ gollum-site serve

Now you can browse to http://localhost:8000 and view the Radiant wiki as a static site.

If you'd like to see generate the radiant wiki with the Gollum layout:

   $ gollum-site import # imports a simple layout
   $ gollum-site generate --working # this is SLOW
   $ gollum-site serve --watch

Now you can browse to http://localhost:8000 and view the Radiant wiki. Additionally, you can make changes to the wiki files that will automatically update in the static site.