Skip to content
Dawa Ometto edited this page Oct 14, 2018 · 101 revisions

Navigate this page:

  1. Setting page titles
  2. Using subpages
  3. Page sanitization (security note)
  4. Gollum tag reference
  5. Gollum code block reference
  6. Gollum macro reference
  7. Gollum diagram reference
  8. Integrating mathematics
  9. Authentication


By default, a page's title will be its file path, relative to repository root (or page file dir), without extension (e.g. /mordor/Sauron).

Custom titles via CLI

If you start Gollum with the --h1-title option, then the first <h1> header on the page will be used. So, for example, this markdown page:

# This is my title
# This is the first h1 that will be displayed

will be rendered with the This is my title page title. The first header rendered in the page's text will be This is the first h1 that will be displayed.

This option overrides the metadata syntax.

Custom titles via the metadata syntax

The syntax:

<!-- --- title: My page title -->

Note that the metadata must be the first piece of text on the page.


Gollum allows you to add a header, sidebar and footer to pages. They will most probably be shared among several pages. Subpages affect all pages in their directory and any subdirectories that do not have a subpage of their own.

  1. Header files are named _Header.ext, where ext is one of the supported formats' extensions.
  2. Sidebar files are named _Sidebar.ext, where ext is one of the supported formats' extensions.
  3. Footer files are named _Footer.ext, where ext is one of the supported formats' extensions.


For security and compatibility reasons, Gollum pages may not contain custom CSS, JavaScript, and potentially dangerous or unknown HTML markup. They will be stripped from the generated HTML. See the Security page for more information.


Gollum's tags have been made to resemble the tags of other markups, especially MediaWiki. The basic syntax is:


Some tags will accept attributes which are separated by pipe symbols. Some attributes must precede the tag and some must follow it:

  • [[prefix-attribute|tag]]
  • [[tag|suffix-attribute]]

Link tag

The link tag creates a clickable link to a resource. It has two forms:

  • [[linked-resource]] - the created link's text will be equal to the resource's text
  • [[link-text|linked-resource]] - the created link's text will be link-text

Linking external resources


  • [[]]
  • [[link-text|]]

Allowed URL protocols are listed here.

Linking internal files (not images or pages)

Identical to linking external resources, but the URLs must be paths:

  • Either a relative path, e.g. docs/diagram.png. Relative paths point to a file relative to the page, where the link is defined. They must not be prefixed with a slash.
  • Or an absolute path, e.g. /docs/diagram.png. Absolute paths point to a file relative to Gollum repository's root. They must be prefixed with a slash.

Linking internal images

Identical to linking internal files, but also supports several special attributes:

  1. [[image-url|alt=text]]
    • Text to display when the image is not found.
  2. [[image-url|frame]]
    • Tells Gollum to place the image in a <span class="frame">, which will display a border around the image.
  3. [[image-url|align=position]]
    • Tells Gollum to align the image in the given way. Position can be left, center, and right. Default: left.
  4. [[image-url|float]]
    • Tells Gollum to float the image so that the text flows around it. This option can not be used with the align=center option. When floating is enabled and alignment is not specified, align=left is applied.
  5. [[image-url|height=value]]
    • Set maximum height for the image. Values must be specified either with px or em unit.
  6. [[image-url|width=value]]
    • Set maximum width for the image. Values must be specified either with px or em unit.

All of these attributes can be combined together simply by separating them with pipes.

Special behaviour:

  1. [[image-url|frame|alt=text]]
    • Tells Gollum to place the image in a <span class="frame"> **and** uses the alt`'s text as its caption.

By default text will fill up all the space around the image. To control how much should show up use this tag to stop and start a new block so that additional content doesn't fill in.


Linking internal pages

The following tag will create a link to another Gollum page:


Canonical page filename is the page's filename, but after applying these rules:

  • Extension is tossed away.
  • Spaces (U+0020) are replaced with dashes (U+002D).
  • Forward slashes (U+002F) are replaced with dashes (U+002D).


  • [[J. R. R. Tolkien]] will reference the J.-R.-R.-Tolkien.ext page
  • [[Movies / The Hobbit]] will reference the Movies---The-Hobbit.ext page
  • [[モルドール]] will reference the モルドール.ext page

The referenced page may exist anywhere in the git repository. Gollum will search for it and link the first such page that it finds.

Include tag

As opposed to the link tag, this one is dedicated to pages, has a special syntax and includes a page into another, rather than linking it:


Table-of-contents (TOC) tag

Gollum provides a special tag for embedding a table of contents into a page:


Or with a max depth

[[_TOC_|levels = 3]]


  • It is case sensitive, so always use uppercase.
  • It can also be inserted into subpages.

There is also a global TOC setting (disabled by default) that forces TOC into every page. Simply add the following line to your configuration file:

Precious::App.set(:wiki_options, { :universal_toc => true })

Escaping tags

In case a tag needs to be displayed on a page literally, preface the tag with a single quote:



Fenced code blocks (GitHub style)

Naturally, all pages can benefit from this syntax. Example:

def foo
    puts 'bar'

The block must be enclosed with three backticks.


  • The opening backticks can be indented arbitrarily.
  • The block's content should be indented at the same level as the opening backticks. If it is indented with an additional two spaces or one tab, they will be ignored (this makes the blocks easier to read in plaintext).
  • The ending backticks must be indented at the same level as the opening backticks.

Fenced code blocks (Kramdown style)

Naturally, all pages can benefit from this syntax. Example:

Here comes some code.

The block must be enclosed with three or more tildes (~).

Syntax highlighted code blocks

This is an extension to GitHub-style code blocks. Naturally, all pages can benefit from this syntax. Example:

def foo
    puts 'bar'

TODO: verify and update this + maybe it's time to recap (

As you can see, the code's language/markup is defined next to the opening backticks. There are a variety of languages/markups to use and they depend on which syntax highlighter is currently used in Gollum:

Additionally, you can syntax highlight a file from your repository. Naturally, when the file is updated and the page refreshed in browser, the code snippet is updated as well:


In this case, the /lib/gollum/app.rb file will be included in the page, and syntax highlighted.


Besides tags, Gollum provides another layer of its own markup - macros. The main differences are:

  • Tags are all predefined and can not be customized. Macros can be customized and you can even create your own.
  • Different syntax.

Default Macros


  • Description: Prints a list of all wiki pages.
  • Syntax: <<AllPages()>>
  • Result (example): <ul id="pages"><li>AllPagesMacroPage</li></ul>


  • Description: Prints a clickable TOC (all pages site wise)
  • Syntax: <<GlobalTOC()>> you can also override the title: <<GlobalTOC("All pages")>>


  • Description: Prints a clickable TOC (of all pages under the indicated path, or under the current page's path by default)
  • Examples:
    • <<Navigation()>>
    • <<Navigation("My TOC", "subdir", true)>>
  • Syntax: <<Navigation(title, subdir, full_path)>>
    • title: string, header above the printed TOC. Defaults to "Navigate in the TOC".
    • subdir: string, the subdirectory to list. Defaults to the current page's path.
    • full_path: true or false. Whether to display the full path to each page, instead of just the relative path under subdir. Default: false.


  • Description: render Next: and Previous: links to navigate through a series of pages in the same directory. You can have a series of pages in a subdirectory named e.g.,, Just add <Series("steps_")>> to them (or in the Header/Footer of course!) to generate links to the previous and following steps. This way you can easily generate, e.g., a step-wise user manual.
  • Usage: <<Series("prefix")>>
    • Will look for all pages with name starting with "prefix", and link to the pages of the series that immediately precede and follow the current page (by page name, alphanumerically sorted).

Custom Macros

Each Macro must:

  1. Subclass the Macro class.
  2. Override the render method.
  3. Be registered in Gollum. Therefore:
    • either start Gollum with the --config option and put your custom Macro class in the config.rb file,
    • or start Gollum via Rack and put your custom Macro class in the file.

For example, look at the implementation of the AllPages Macro.


  • If you have created a useful Macro, please consider making a pull request to gollum-lib.
  • If you have an idea for a useful Macro, please consider creating an issue for gollum.


Sequence diagrams

Gollum can render sequence diagrams from source on a page. Courtesy of WebSequenceDiagrams. For example:

{{{{{{ blue-modern
    alice->bob: Test
    bob->alice: Test response

You can replace the blue-modern style with any other supported style. Open the link above to discover what styles are available.

PlantUML diagrams

If you install and configure your own PlantUML server, Gollum can render PlantUML diagrams from source on a page. Courtesy of PlantUML. For example:

Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response

You can embed any of the diagram types supported by PlantUML: sequence diagrams, case diagrams, class diagrams, activity diagrams, component diagrams, object diagrams and even wireframe diagrams.


  • For wireframe diagrams, you must use the *@startuml* tag followed by the *salt* keyword syntax. The new *@salt* syntax is not supported. See link.
  • There cannot be empty lines inside the @startuml/@enduml block. PlantUML expects a single paragraph and adding empty lines in between will be read as multiple paragraphs.
  • If you do not want to use your own PlantUML server, you can configure as the server to use. See here on how to configure which server to use.


To enable mathematical expressions in Gollum, start it with the --mathjax option. We recommend this page to learn about the syntax.


  • Inline math:
  • Display math:

By default, Gollum uses the TeX-AMS-MML_HTMLorMML config with the autoload-all extension. You can also set your own mathjax configuration with the --mathjax-config option.


  • When using the Org-mode markup, you will have to wrap display math blocks in #+BEGIN_HTML ... #+END_HTML blocks.


Out of the box, Gollum doesn't support user authentication.

A separate project exists, OmniGollum, that adds OmniAuth for Gollum. With OmniGollum one can add numerous OAuth providers (Github, Google, etc) to perform authentication.

There are some third party guides to add secure authentication to Gollum via OmniGollum:

You can’t perform that action at this time.