Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Home

Dawa Ometto edited this page · 58 revisions

Navigate this page:

  1. Subpages
  2. Sanitization
  3. Tags
  4. Code Blocks
  5. Macros
  6. Mathematics

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.

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 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: New Title -->

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

PAGE SANITIZATION

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

TAGS

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

[[tag]]

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

Examples:

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

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 an <iframe>.
  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 an <iframe> and uses the alt's text as its caption.

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

[[cannonical-page-filename]]

Cannonical 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).

Examples:

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

[[include:cannonical-page-filename]]

Table-of-contents (TOC) tag

Gollum provides a special tag to embed table of contents into a page:

[[_TOC_]]

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)

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:

```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

Beside 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

AllPages

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

Custom Macros

Each Macro must:

  1. Subclass the abstract 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.

DIAGRAMS

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:

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

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:
    text $$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 with the --mathjax-config option.

Notes:

  • When using the Org-mode markup, you will have to wrap display math blocks in #+BEGIN_HTML ... #+END_HTML blocks.
Something went wrong with that request. Please try again.