Custom Styling and Views

Using custom.css and the --css flag

You can add custom styling to gollum by adding CSS to a custom.css file in gollum's root. Use gollum's --css flag to load this file, or, if you are running gollum as a Rack app, set wiki_options[:css] = true. Note that custom.css must be committed to the repository for this to take effect.

As an example (5.x only), consider changing the widths of the page body and sidebar and changing the bullet style to squares.

.main-content {
  max-width: 90%;
}

#wiki-sidebar {
  width: 17%;
}

ul {
  list-style-type: square;
}

Using custom.js and the --js flag

Some styling that cannot be modified via custom CSS may still be modifiable via custom JavaScript. Use gollum's --js flag to load the custom.js file, or, if you are running gollum as a Rack app, set wiki_options[:js] = true. Note that custom.js must be committed to the repository for this to take effect.

Changing the editor colorscheme and styling

This snippet in custom.js will change the ACE editor's theme to clouds:

$(document).ready(function () {
window.ace.config.setModuleUrl(
    "ace/theme/clouds", 
    "http://ajaxorg.github.io/ace-builds/src-noconflict/theme-clouds.js" // Gollum does not include all ACE themes for performance reasons, so tell ACE where to find the themes online.
)
window.ace_editor.setTheme('ace/theme/clouds') // Set theme to clouds
window.ace_editor.setOption("showPrintMargin", false) // Optionally turn off the print margin (vertical line)
})

For more editor options you can tweak, see the ACE documentation. For a list of available ACE themes, see here. You can try out the different ACE themes here.

Changing the sidebar position

By default, the sidebar is positioned to the right of the page. To move the sidebar to the left, simply add the following to the wiki_options hash: wiki_options[:sidebar] = :left.

Customizing views

Though most custom styling can be achieved using custom.css, sometimes you may want full control over the elements in the pages. For this, you can copy individual mustache templates from gollum to a location of your choosing, modify the templates, and use the --template-dir [PATH] directive to point gollum to your custom views.

As of 5.3 (unreleased at the time of this writing), Gollum supports partial template overrides. It will look in the --template-dir for any Mustache layout or partial first before falling back to its own internal directory.

To override only the navbar for example:

• Create a local templates/ directory, next to your config.rb or config.ru.
• Copy the navbar.mustache file from your gollum gem location into that folder.
  • (You can locate where the gollum gem is installed using gem which gollum.)
• Add --template-dir templates to your gollum command line, or add template_dir: 'templates' to wiki_options in your config.rb.
• Restart gollum.

With this configuration in place, you can now edit the new local copy of templates/navbar.mustache to include your desired changes. Any partials that your overridden .mustache file references can exist either alongside your customized template, or you can re-use existing partials from Gollum.