Skip to content

6.0 Release Notes

Jump to bottom Edit New page
Dawa Ometto edited this page May 2, 2024 · 18 revisions

These are release notes for the 6.0 release of Gollum. These notes detail the major changes in the new release, which in some instances will require tweaking your existing setup. See below for the steps needed to get your wiki running on 6.x.

Overview of the largest new changes:

In addition, Gollum 6.0 includes myriad bugfixes, improvements to accessibility and styling, improvements to stability and maintainability, and performance increases! 🚀

Migrating your wiki

If you are migrating from a wiki running gollum < 5.0, read the migration steps for 5.0 first.

  1. Default branch: as of 6.0, main will be used if present, with master as a fallback option (details).
  2. If you are using a matjax.config.js, git rename it to math.config.js (details).
  3. Docker image: use the --math flag to enable mathematics (in earlier version, this flag was implicit, but this was deprecated).
  4. PlantUML: if you are using a remote PlantUML server (such as the standard plantuml.com), you must now configure this explicitly. By default, Gollum now tries to use a local PlantUML server. This for safety reasons: in the previous setup, Gollum was automatically and without clear notice sending diagrams over the internet. Note that you can now also use Mermaid for rendering diagrams without need for any server.

Default branch detection

Previously, Gollum would assume master as the default branch. If this branch did not exist, and the user did not explicitly set a different branch (--ref), an error would be thrown. It has become common practice everywhere to abandon master as a default git branch name. main has instead been adopted by many parties, including GitHub and GitLab.

Until 6.0, main needed to be set explicitly using the --ref command line option. As of 6.0, Gollum supports more flexible detection of a wiki's branch.

In short: if your repository uses main, everything will work out of the box on 6.0 (no need to specify --ref). Support for master as a default branch remains for backward compatibility reasons, for now. (If a wiki has both master and main branches, main will be utilized by default.)

Here is a more detailed description of how Gollum will try to find the branch that it will try to use:

  1. If there is an explicit branch set by the user (--ref), that will be used.
  2. If not, Gollum will try the branch names in Wiki.default_refs in order (main, then master).
  3. If none of these exist, Gollum will see if there is a global git default branch name set (using git config) and use it.
  4. If not, it will try to use main after all (whether main exists or not).

Mathematics

Support for KaTeX (default) in addition to MathJax

Gollum now supports KaTeX as a renderer for mathematics in addition to MathJax. KaTeX is now also the default renderer. In the future, support for MathJax may be discontinued, as KaTeX is easier to bundle and maintain. KaTeX is also generally faster than MathJax.

Note: KaTeX supports almost exactly the same syntax as MathJax, so in most cases it should not matter which renderer you are using. See here for a list of TeX functions supported by KaTeX.

This change means that Gollum 6.0 introduces a new command line option to enable mathematics: --math. The --mathjax option still works, but is deprecated.

Customizing the configuration of KaTeX and MathJax has also changed.

Docker image: in earlier versions of the Docker image, mathematics support was automatically enabled. However, this was deprecated. You should now use the --math flag to enable mathematics.

Enabling mathematics (KaTeX)

Use the --math command line option to enable mathematics rendering using KaTeX (default). This is equivalent to --math katex.

Enabling mathematics (MathJax)

Use the --math mathjax command line option to enable mathematics rendering using MathJax. This is equivalent to --math mathjax.

Enabling mathematics in config.rb

Previously, it was possible to enable mathematics support in config.rb by setting the following option:

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

You can now equivalently do the following:

wiki_options = {
    math: :mathjax # For MathJax
    #math: :katex # For KaTeX
}
Precious::App.set(:wiki_options, wiki_options)

Note: The --mathjax option is shorthand for --math mathjax, but using --mathjax is discouraged and deprecated.

Configuring mathematics rendering

Both KaTeX and MathJax are enabled with a sane set of defaults when using the --math command line option. However, it is also possible to use your own customized configuration.

Previously, Gollum supported customizing MathJax settings via the mathjax.config.js file. To reflect that Gollum now supports KaTeX in addition to MathJax, this file has been renamed to math.config.js.

Note: remember that math.config.js must be commited to the repository in order to function! Note: if you are already using a custom.js file with the --js option, you can also add your MathJax or KaTeX configuration to that file.

Configuring MathJax

In math.config.js, add the following:

window.MathJax = {
 // your MathJax config here
 // see https://docs.mathjax.org/en/latest/web/configuration.html#configuring-mathjax
};

Configuring KaTeX

In math.config.js, define the special katex_conf variable to provide your own configuration:

var katex_conf = {
    // These are the default options
    // See https://katex.org/docs/options for more options
    delimiters: [
        {left: '$$', right: '$$', display: true},
        {left: '$', right: '$', display: false},
        {left: '\\(', right: '\\)', display: false},
        {left: '\\[', right: '\\]', display: true}
    ],
    throwOnError: false
};

Mermaid

Gollum now has support for Mermaid diagrams.

Misc

  • RACK_ENV is ignored, please use APP_ENV instead (@svoop).
  • Add support for more languages (Chinese).
  • Add support for downloading page sources with ?raw (@tstein).
  • Add openssh client to docker images for ssh: repo support (@jagerkin).
  • Support for custom language handlers (@dometto).
  • Support for adding git notes to commits (@dometto, @bartkamhorst).
  • JQuery was updated from 1.7.2 to 1.9.1. This means that $.browser is no longer available.
Add a custom sidebar
Clone this wiki locally