Skip to content

Home

Jump to bottom
Tevin edited this page Feb 8, 2022 · 155 revisions
Clone this wiki locally

Welcome to the Gollum wiki! See the documentation below, or view screenshots of some of Gollum's features.

NB: Gollum and GitHub wikis have diverged. If you are reading this on GitHub, there are thus some very significant differences between the platform you're currently using and Gollum. If you want to test Gollum, give it a quick try by installing it, or view some of the screenshots. Plans to create a live demo are being tracked here -- all help is much appreciated!

Table of Contents:

  1. Hotkeys
  2. Setting page titles
  3. Using subpages
  4. Page sanitization (security note)
  5. Gollum tags
  6. Gollum code blocks
  7. Gollum macros
  8. YAML Metadata for Pages
  9. Gollum diagrams
  10. Mathematics
  11. Bibliographies, citations, and footnotes
  12. CriticMarkup
  13. Redirects
  14. Authentication
  15. Miscellaneous Features
  16. Migrating From Other Wikis

HOTKEYS

On a Page

  • e: Edit the Page

In the Editor:

  • Ctrl/Cmd-S: Save
  • Ctrl-Shift-P: Toggle Preview

PAGE TITLES

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 CLI1

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.

Metadata titles

The syntax:

---
title: My Overriden Title
---

Note that the YAML metadata must be the first piece of text on the page. See Metadata for more info.

SUBPAGES

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.

Using the --template-page option, you can also use _Template file that will be used as the template for creating new pages. You can have different _Template files in different directories.

Template Filter

Placeholders could be used in templates as well, here's an example:

In config.rb:

Gollum::TemplateFilter.add_filter('{{current_date}}', & -> () { Time.now.strftime("%Y-%m-%d") })

In your template:

# Daily Log, {{current_date}}

PAGE SANITIZATION

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.

TAGS

Note: Gollum's tag syntax [[tag]] conflicts with asciidoc's bookmark syntax. On Asciidoc pages, gollum's support for tags is thus turned off by default. See here for more info on how to turn it on.

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 internal pages

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

[[Bilbo Baggins]]

Or to disambiguate:

[[Bilbo Baggins.md]]
[[Bilbo Baggins.rst]]

Gollum's links resolve in the following way:

  • a link [[Foo]] will try to find a matching page Foo in the same directory as the linking page.
  • If you have a file Foo in your repository root, and want to link to it from a page inside a subdirectory (e.g. Subir/Bar), use an absolute path: [[/Foo]].
    • When using Gollum's --lenient-tag-lookup option, a link [[Foo]] will resolve the first page with filename Foo anywhere in the wiki (still looking in the same directory, first). This mimics the behavior of older Gollum versions.

In previous versions of gollum, there were various limitations regarding filenames and internal linking that have been removed in version 5.0. See here for an overview of the changes.

Note that you can also use whatever link syntax is used by a page's markup language. For example, on a Markdown page, you can use [link text](href) style pages. But these will be handled by the markup rendering gem, and not by gollum.

Anchors

To link to a specific section in a file, use [[Page.md#gollum]]. Previously, the anchors would get very large because, in order to guarantee that every anchor was unique, they would include the headers above it, e.g. #main-header_sub-header_sub-sub-header. Instead, gollum now generates anchors according to the same scheme as GitHub:

# Ecthelion

## Boromir

## Faramir

# Boromir

## Ecthelion

...generates these anchors:

#ecthelion
#boromir
#faramir
#boromir-1
#ecthelion-1

Linking external resources

Examples:

  • [[http://example.com]]
  • [[link-text|http://example.com/pdfs/gollum.pdf]]

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 commas. (Note: in older versions of gollum, < 5.0, the separator used to be a pipe symbol). For example:

  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.

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:

[[include:path-to-page]]

Table-of-contents (TOC) tag

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

[[_TOC_]]

Or with a max depth

[[_TOC_|levels = 3]]

Notes:

  • 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:

'[[tag]]

CODE BLOCKS

Fenced code blocks (GitHub style)

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

```
def foo
    puts 'bar'
end
```

The block must be enclosed with three backticks.

Indentation:

  • 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)

This syntax is available on Markdown pages when using the default kramdown renderer.

~~~~~~~~
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:

```ruby
def foo
    puts 'bar'
end
```

TODO: verify and update this + maybe it's time to recap (https://rubygems.org/search?utf8=%E2%9C%93&query=pygments)

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:

```ruby:/lib/gollum/app.rb```

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

MACROS

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

See here for a list of macros that gollum supports out of the box!

Custom Macros

You can create your own custom macros for gollum-lib. 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 config.ru file.

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

Notes:

  • 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.

METADATA

Gollum supports the use of YAML front matter, just as in e.g. jekyll. (In versions < 5.0, Gollum supported its own metadata syntax, which has been discontinued.)

Use the following syntax at the start of your document:

---
key: value
---
# Rest of the document here

Or you can close the YAML block with ... instead of ---.

Gollum-predefined keys

Gollum looks for certain predefined keys in your YAML front matter to customize certain settings:

  • title: see above
  • display_metadata: set to false in order to stop the front matter from being rendered when viewing your page (see Rendering front matter.
  • header_enum: see Header counting
  • ...more may be added in the future!

Global metadata

You can also set global metadata for the wiki, which will be merged into each page's specific metadata. This way you can easily enable some settings for each page on the wiki. If a metada key is defined on the page it will override the same key in the global metadata. To use this, just define the :metadata key for your options hash when using a config.rb:

Precious::App.set(:wiki_options, { :metadata => {'foo' => 'This will show up as metadata on each page!'} })

Rendering front matter

By default, gollum renders YAML front matter at the start of the page in a table, similar to github. This will look as follows:

YAML Frontmatter Preview

However, gollum will not render the table when the only keywords used in the front matter are title and header_enum, i.e. when the front matter is used only to override the page's title or to enable header counting.

If you do not wish front matter to be displayed in this matter, there are two options:

  • disable globally by running gollum with the --no-display-metadata command line option
    • or equivalently, by setting the wiki option :display_metadata in your config.rb to false
  • disable on a per-page basis:
    • simply set display_metadata: false in your front matter!

Enabling header counting

Using YAML frontmatter, you can enable header counting on a page. For instance:

---
header_enum: true
---

See the result here.

But it is also possible to specify another counter style, e.g. lower-roman, upper-alpha, etc. See here for a list of valid values. Example:

---
header_enum: 'tibetan'
---

See the result here.

DIAGRAMS

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:

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

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.

Notes:

  • 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 https://www.plantuml.com/plantuml/png as the server to use. See here on how to configure which server to use.

MATHEMATICS

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

Examples:

  • Inline math: 
    \\\(2^2\\\)
  • Display math: 
    $$2^2$$
\\\[2^2\\\]

By default, Gollum uses the TeX-AMS-MML_HTMLorMML config with the autoload-all extension. You can also set your own mathjax configuration by comitting a file named mathjax.config.js to the root of the repository and it will automagically be used.

Here is an example mathjax.config.js that will use one \ instead of three \\\ to begin a mathjax formula:

window.MathJax = {
  tex2jax: {
    inlineMath: [['$', '$'], ['\(', '\)']],
    displayMath: [['$$', '$$'], ['\[', '\]']],
    processEscapes: true
  },
  TeX: {extensions: ['autoload-all.js']}
};

Notes:

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

Bibliographies, citations, and footnotes.

Gollum comes with support for BibTeX bibliographies, as well as citations and footnotes in Markdown documents. Read more here.

CriticMarkup Annotations

Gollum now supports CriticMarkup annotations to suggest deletions or additions and add comments. Start gollum with the option --critic-markup to enable it. The editor features new minibuttons for CriticMarkup-related actions.

Screen Shot 2020-03-23 at 17 53 01

Redirects

Gollum supports redirects: after a page is renamed, visiting the old page will automatically send you to the new location. This works via a YAML file called .redirects.gollum which should be located in and committed to the root of the gollum repository. Redirects are automatically added after page renames. They may also be added manually by adding entries to the YAML file directly. The format is a straightforward hash with format old_path: new_path:

---
Home.old.md: Home.md
subdir/Home.md: Home.md
tobemoved.md: wastobemoved.md

This feature is enabled by default. Setting :redirects_enabled to false in config.rb will disable this feature.

Authentication

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:

Miscellaneous Features

Migrating From Other Wikis

The caramelize project provides functionality allowing you to migrate from other wiki systems to Gollum. It has out of the box support for WikkaWiki and Redmine Wiki, but also offers an API for defining other input wiki systems.