Custom rendering gems

Gollum uses the github-markup gem to render the various supported markup formats. By overriding some of github-markup's constants, you can use custom gems for rendering that aren't supported out of the box. To do this, start gollum with the --config option and add the overriding code to your config.rb. Some examples below.

Custom markdown rendering gems

By default, github-markup supports a number of markdown rendering gems, which each have their own specific syntax and features. See here for a list. Gollum comes with the kramdown gem out of the box, and that will be used unless you have installed one of the other gems that github-markup supports.

Using MultiMarkdown

You can use the rmultimarkdown gem to use MultiMarkdown syntax as follows:

• First, gem install rmultimarkdown
• Then, add to your config.rb:

require 'rmultimarkdown'
module Gollum
  class Markup
    mmd = proc { |content|
     MultiMarkdown.new(content).to_html
    }
    GitHub::Markup::Markdown::MARKDOWN_GEMS['rmultimarkdown'] = mmd
    GitHub::Markup::Markdown::MARKDOWN_GEMS.delete('kramdown') # You may want to disable support for kramdown to ensure that rmultimarkdown is actually used
  end
end

Changing github-markup's default rendering settings

Apart from adding new custom rendering gems, you can also change the default settings that github-markup and gollum use.

Chaing asciidoctor's default settings

GitHub::Markup.markups.reject! {|name| name == :asciidoc }

GitHub::Markup.markup(:asciidoc, :asciidoctor, /adoc|asc(iidoc)?/, ["AsciiDoc"]) do |filename, content|
  Asciidoctor::Compliance.unique_id_start_index = 1 # Example, not needed
  # Attributs that you can change:
  myattrs = {
    'showtitle' => '@',
    'idprefix' => '',
    'idseparator' => '-',
    'sectanchors' => nil,
    'env' => 'github',
    'env-github' => '',
    'source-highlighter' => 'html-pipeline'
  }
  Asciidoctor.convert(content, :safe => :secure, :attributes => myattrs)
end

Changing the kramdown rendering options

As explained above, kramdown is the rendering gem that gollum uses out-of-the-box. See here for an overview of kramdown's options.

    GitHub::Markup::Markdown::MARKDOWN_GEMS['kramdown'] = proc { |content|
        Kramdown::Document.new(content, :input => "GFM", :auto_ids => false, :math_engine => nil, :smart_quotes => ["'", "'", '"', '"'].map{|char| char.codepoints.first}).to_html
    } # This shows the defaults options for kramdown (on gollum 5.x), change the options hash to get the desired results.

Changing the commonmarker rendering options

To change commonmarker parsing options put this in your config.rb:

GitHub::Markup::Markdown::MARKDOWN_GEMS['commonmarker'] = proc { |content, options: {}|
  CommonMarker.render_doc(content, [:FOOTNOTES]).to_html # Your parsing options here
}

To customise rendering options use:

GitHub::Markup::Markdown::MARKDOWN_GEMS['commonmarker'] = proc { |content, options: {}|
  CommonMarker.render_html(content, [:HARDBREAKS]) # Your rendering options here
}

To customise parsing and rendering options at the same time pass parsing options to render_doc and rendering options to to_html:

GitHub::Markup::Markdown::MARKDOWN_GEMS['commonmarker'] = proc { |content, options: {}|
  CommonMarker.render_doc(content, [:FOOTNOTES]).to_html([:HARDBREAKS]) # Your options here
}