5.0 release notes

These are release notes for the 5.0 release of gollum and gollum-lib. These notes detail the major changes in the new release, which in some instances will require adapting existing wikis for them to continue working. See below for the steps needed to get your wiki running on 5.x.

The changes:

1. Filename handling
2. YAML Frontmatter
3. Header counting
4. New Anchor Naming
5. Bilbiographies, Citations, and Footnotes
6. Escaping emoji tags
7. The --page-file-dir option is now invisible to the user
8. Video and Audio Macros
9. Note and Warn Macro
10. Octicon Macro
11. Support for Redirects
12. Image Tag Options
13. Annotations with CriticMarkup
14. Right to Left Text
15. Secure Custom CSS and JS
16. Editable Sections
17. New Layout
18. RSS Feed

Filename handling

No global file names

In previous versions of gollum, a link such as [[Bilbo]] would match a page named Bilbo anywhere in the repository (including in nested subdirectories). This is no longer the case by default for performance reasons, and because it made it unclear to which resource a tag referred. Gollum will try to resolve relative links to a page in the same directory as the page you're linking from. So if you have the following repository:

Bilbo
Dir/Bilbo
Dir/Foo

...a tag [[Bilbo]] in Dir/Foo will link to Dir/Bilbo. If you want to link to page Bilbo in the repository root from a subdirectory, specify an absolute path: [[/Bilbo]]

However, see below for the --lenient-tag-lookup option.

You can use the gollum-migrate-tags script, packaged with Gollum 5.x, to convert 4.x style tags that are broken on 5.x.

Filenames are now case sensitive

Before v5.0, gollum filenames and URLs were not case-sensitive. They are now. This is to ensure that a link or URL to page determines a unique resource. So [[Bilbo]] will no longer find the page bilbo.

However, see below for the --lenient-tag-lookup option.

You can use the gollum-migrate-tags script, packaged with Gollum 5.x, to convert 4.x style tags that are broken on 5.x.

Filenames can contain utf-8 characters

Use spaces in filenames

Before v5.0, gollum would automatically remove spaces (and other whitespace) in the names of your pages and files and replace them with hyphens (-) or underscores (_). Thus, files committed to your repository on the command line whose names contained whitespace could not be read or modified in gollum. This restriction has now been removed.

Note:

• previously, http://localhost:4567/some page/ would yield the page some-page.ext from the repository (if it existed)
• now, that URL will yield the page some page.ext (with whitespace!)
• so you can have two distinct files in your repository that gollum will both recognize as valid pages:
  • some page.ext
  • some-page.ext
• therefore, internal links are not longer whitespace agnostic. The following links link to different pages:
  • [[Some page]]
  • [[Some-page]]

However, see below for the --lenient-tag-lookup option.

You can use the gollum-migrate-tags script, packaged with Gollum 5.x, to convert 4.x style tags that are broken on 5.x.

Use file extensions

Before v5.0, gollum would be agnostic about file extensions. For example, http://localhost:4567/somepage/ would yield the page somepage.md from the repository (if it existed). But http://localhost:4567/somepage.md would not yield a valid page. Gollum now handles explicit file extensions. This means you can (but need not) use explicit file extensions to access and link to files.

For instance, you can now have multiple files with the same name, but different extensions, in your repository in the same directory, and Gollum will all be able to serve them all as valid files:

• somepage.md
• somepage.textile
• etc.

Simply go to e.g. http://localhost:4567/somepage.textile to request the page in question.

You can also use internal links with explicit file extensions. The following links link to different pages:

• [[somepage.md]
• [[somepage.textile]]

However, you can still leave the file extension for a page implicit. That is, given that you have a page somepage.md in your repository, you can:

• link to it with [[somepage]]
• or view it at e.g. http://localhost:4567/somepage
• Note: if there are multiple pages with the same name, but different examples, requesting the page without explicitly listing the file extension will simply yield the page that is first found in the repository (i.e., alphanumerically: first .md and only then .textile).

Compatibility Option

The new --lenient-tag-lookup option provides backward compatibility for all the above differences with 4.x tag lookup (except that utf8 filenames are now allowed):

• Process spaces in page names as hyphens
• Resolve page names case-insensitively
• Lookup page names globally

You can also enable each of these compatibility options individually in a config.rb:

Precious::App.wiki_options[:hyphened_tag_lookup] = true
Precious::App.wiki_options[:case_insensitive_tag_lookup] = true
Precious::App.wiki_options[:global_tag_lookup] = true

Note that this also mimics the behavior of GitHub and GitLab wikis.

Metadata: YAML Frontmatter

No more custom metadata tags

Gollum < 5.0 used to support custom metadata tags: <!-- --- title: My page title --> Support for these tags has been removed, but instead...

YAML

...you can use YAML front matter, just as in e.g. jekyll. 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 Custom titles
• 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!'} })

Custom titles

Just as with old-style metadata tags, you can use YAML front matter to override the page's title:

---
title: My Overriden Title
---

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:

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

Result:

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

Result:

Anchors

To link to a header (e.g. # Gollum in Markdown) on a page, 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 

Bibliographies, citations, and footnotes.

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

Escaping emoji tags

Emoji tags like :shell: work great when you write about your last trip to the Caribbean, laying on a sandy 🏖 peppered with 🐚. However, this particular emoji gets in your way with something like rake app:shell:install. As of v5.0 you can disable individual emoji tags by adding a backslash in front of it:

• rake app:shell:install -> rake app:shell:install
• rake app\:shell:install -> rake app:​shell:install

--page-file-dir option is now invisible to the user

Using the :page_file_dir option allows you to base the wiki in a subpath of the repository. Until 5.0, using :page_file_dir => 'docs' would use the 'docs' directory as source of files for the wiki, but it would also serve the wiki under the URL http://127.0.0.1:4567/docs/.

In 5.x, the URL for the wiki will instead remain 127.0.0.1:4567 (while pages will still be served out of the 'docs' directory). If you want to prefix docs to the URL at which the wiki is served, you can accomplish this using the :base_path option.

Video & Audio Macro

You can now link to video files using the Video macro. The macro generates a simple HTML5 video tag that allows you to play and control the video on your Gollum wiki page.

• Syntax: <<Video(/pathname/filename)>>
• Example: <<Video(/uploads/product_tutorial.mp4)>>

Similarly for <<Audio(path)>>.

Note & Warn Macro

You can now add alerts to pages with the Note and Warn macros. These macros generate colored flash boxes to highlight important information. Each flash box by default also shows an octicon icon, but for notes this icon can be changed or disabled altogether.

• Note Syntax: <<Note(string[, string])>>
  • Example 1: <<Note("Did you know?")>>
  • Example 2: <<Note("Did you know?", "bell")>>
  • Example 3: <<Note("Did you know?", "")>>

• Warn Syntax: <<Warn(string)>>
  • Example: <<Warn("Careful, changing that file could be dangerous")>>

Octicon Macro

You can also add any Octicon icon to your page using the new Octicon macro. This macro takes a string name of the desired octicon and optional dimension parameters (width, height, respectively).

• Syntax: <<Octicon(string[, integer, integer])>>
• Example: <<Octicon("globe", 64, 64)>>

Support for redirects

Gollum 5.x now supports redirects. 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.

Image Options

Previously, you could combine gollum's image options using pipes (|). Now, you must separate image options with a comma. So the correct syntax is now e.g.:

• [[path/image.jpg|align=center,frame,alt=Bla]]

Support for annotations using CriticMarkup

Gollum now supports CriticMarkup annotations to suggest deletions or additions and add comments. The editor features new minibuttons for CriticMarkup-related actions.

Support for Right-To-Left direction text

This is essential for supporting languages (or scripts) that flow from right to left. There are two ways RTL is supported:

• in the editor, the user can now switch the direction of the text on a per-line or per-selection basis with Ctrl-alt-shift-R or Ctrl-alt-shift-L (Cmd instead of Ctrl on Mac).
• There is a minibutton that switches the text direction for the entire editor.

When viewing a page, Gollum will render text in a Right-To-Left language correctly. Whether a paragraph is rendered LTR or RTL is determined by its first character: if the first character is from an RTL script, the whole paragraph is rendered RTL (this behavior is due to the HTML5 dir=auto attribute).

The Gollum editor will automatically switch to RTL if it detects that the first line of the document is RTL.

See a screenshot here.

Secure custom.css and custom.js

Until 5.0, everyone with write access to the wiki could edit the custom CSS and JS files, which was a serious security concern. Editing those files via the app has now been blocked, so you can use custom CSS and JS with public-facing instances of Gollum.

Editable sections

In 5.x, hovering on a section header in a page will usually display two icons:

• a link/anchor icon to the left of the header: allows you to copy the section anchor.
• an edit/pencil icon to the right of the header: clicking this will open the page for editing, and automatically scroll the editor and cursor to the requested section!

Exceptions: some links will display their link icon, but not the edit icon. This is because gollum has determined that it will not be able to find the section in the page's source. This will be the case when the header contains gollum-specific syntax, of which the editor is unaware. For example: # [[A header with a link]]

Gollum uses the ACE editor's syntax highlighting feature to find a specific section in the editor. The 'edit sections' functionality is therefore only available for formats for which ACE highlighting modes exist. At the moments, editable sections are supported for:

• markdown
• asciidoc
• textile
• rst

It is possible that in rare cases, gollum won't be able to find the section header you've clicked in the editor. This may be the case, for instance, when you're using Macros to generate headers on a page. Since the headers don't exist in the source document yet, gollum will be unable to find your section in the editor.

New Primer.css layout

Gollum's new layout is based on Github's Primer.css and uses Github's Octicons as well. Note that the new styling might interfere with existing custom.css files.

RSS Feed

Under /gollum/feed/, you can now find an RSS (v2.0) feed of the latest changes to the wiki. It shows the most recent X changes, where X is determined by the :pagination_count option (10 by default). You can change this option in a config.rb:

Precious::App.wiki_options[:pagination_count] = 15

Migrating your wiki

Steps to update your wiki for compatibility with 5.x.

1. Check for broken links
   • Due to no more global filenames, the ability to use spaces in filenames, and case-sensitive filenames, some links in your existing wiki may be broken. For instance, a link like [[Bilbo-Baggins]] would previously link to a page with the filename Bilbo Baggins, but will now be a broken link. To fix it, just change it to [[Bilbo Baggins]].
   • You can use the packaged migration script to assist you with this task. Alternatively, you can enable the compatibility option to restore the old behavior.
   • Another source of broken links may be the new behavior of the --page-file-dir option: whereas, when using the page file directory 'docs', you could link to a file [[docs/Bilbo]], the correct link is now just [[Bilbo]].
2. Replace your metadata tags with YAML frontmatter.
3. Update your anchors (internal page links) to conform to the new scheme.
4. Update the syntax for your image tags.
5. Support for WSD (Web Sequence Diagrams) has been phased out. You can move to PlantUML, which by default uses the server at https://plantuml.com. However, using PlantUML you can also run your own server.
   • See the documentation for using PlantUML in gollum
   • If you were already using PlantUML, beware: gollum would by default try to use a PlantUML server running on localhost, but now it will use the remote server at https://plantuml.com by default. Updating to gollum 5.x may result in silently switching to the remote server unless you do explicitly configure gollum to use your own PlantUML server.

Migration Script

Gollum 5.x ships with the gollum-migrate-tags script, which helps to convert 4.x style tags that are broken on 5.x. See above for more info.

Run gollum-migrate-tags --help for more info. Of course, the script comes without warranty (but it is tested).

Note: the migration script is at present a little primitive and requires the path to the repository to be the first argument: for instance, gollum-migrate-tags /path/to/repo --write is correct. Passing --write as the first argument will trigger a Rugged::OSError failed to resolve path.

Bugfixes

• The GlobalTOC() and Navigation() Macros now work with the base_path option. Issue. Thanks to @Agilus.
• Fixed bugs preventing use of slashes in base_paths (See #1149 and #1252).
• Fixed bug with breadcrumb on /pages.
• Fixed bug with post_commit hooks not having access to an up-to-date working directory.