Formats and extensions

Gollum supports several markup formats. When creating a new page, you can choose the target markup via a dropdown. This directly determines the new page's file extension (primary extension for the given markup). Also, Gollum has a predefined set of extensions for each markup.

See below for instructions on how to customize formats.

All of the above can be displayed by invoking puts Gollum::Markup.formats.inspect in the context of Gollum:

{:markdown=>
  {:name=>"Markdown",
   :extensions=>["md", "mkd", "mkdn", "mdown", "markdown"],
   :reverse_links=>false,
   :skip_filters=>nil,
   :enabled=>true},
 :rdoc=>
  {:name=>"RDoc",
   :extensions=>["rdoc"],
   :reverse_links=>false,
   :skip_filters=>nil,
   :enabled=>true},
 :txt=>
  {:name=>"Plain Text",
   :extensions=>["txt"],
   :reverse_links=>false,
   :skip_filters=>
    #<Proc:0x00007ff180940678@.../markups.rb:73>,
   :enabled=>true},
 :textile=>
  {:name=>"Textile",
   :extensions=>["textile"],
   :reverse_links=>false,
   :skip_filters=>nil,
   :enabled=>true},
 :org=>
  {:name=>"Org-mode",
   :extensions=>["org"],
   :reverse_links=>false,
   :skip_filters=>nil,
   :enabled=>false},
 :creole=>
  {:name=>"Creole",
   :extensions=>["creole"],
   :reverse_links=>true,
   :skip_filters=>nil,
   :enabled=>false},
 :rst=>
  {:name=>"reStructuredText",
   :extensions=>["rest", "rst"],
   :reverse_links=>false,
   :skip_filters=>nil,
   :enabled=>true},
 :asciidoc=>
  {:name=>"AsciiDoc",
   :extensions=>["asciidoc"],
   :reverse_links=>false,
   :skip_filters=>[:Tags],
   :enabled=>false},
 :mediawiki=>
  {:name=>"MediaWiki",
   :extensions=>["mediawiki", "wiki"],
   :reverse_links=>true,
   :skip_filters=>nil,
   :enabled=>false},
 :pod=>
  {:name=>"Pod",
   :extensions=>["pod"],
   :reverse_links=>false,
   :skip_filters=>nil,
   :enabled=>true},
 :bib=>
  {:name=>"BibTeX",
   :extensions=>["bib"],
   :reverse_links=>false,
   :skip_filters=>
    #<Proc:0x00007ff18095a618@../markups.rb:96>,
   :enabled=>true}
}

Only pages with one of the above extensions are rendered by Gollum.

Customization

You can easily override (parts of) the above configuration. Start Gollum with the --config option and put the below into your config.rb file. Or in case you're starting Gollum via Rack, instead put the code into config.ru.

This example changes the definition for the :asciidoc format by adding the .asc extension and setting that to the primary extension:

# Copy the old format definition
asciidoc = Gollum::Markup.formats[:asciidoc]
# Remove the old format definition
Gollum::Markup.formats.delete(:asciidoc)
# Modify the format definition
asciidoc[:extensions] = ['asc', 'asciidoc'] # The first extension will be used as the default extension for this format (when creating a new page)
# Re-register the format
Gollum::Markup.register(:asciidoc, asciidoc[:name], asciidoc)

Example enabling Gollum tag filters for Asciidoc

The Tag filter is turned off by default on Asciidoc pages, because it conflicts with Asciidoc's bookmark syntax. You can override this and turn on Gollum Tags on Asciidoc pages as follows:

# Copy the old format definition
asciidoc = Gollum::Markup.formats[:asciidoc]
# Make changes to the definition
asciidoc.delete(:skip_filters)
# Remove the old format definition
Gollum::Markup.formats.delete(:asciidoc)
# Modify the format definition
asciidoc[:extensions] = ['asc', 'asciidoc'] # The first extension will be used as the default extension for this format (when creating a new page)
# Re-register the format
Gollum::Markup.register(:asciidoc, asciidoc[:name], asciidoc)

Example enabling support for Fountain

Support for rendering Fountain Markup can be added by using Pandoc and the Pandoc lua filter for Fountain. Steps:

1. Install Pandoc
2. gem install pandoc-ruby
3. Install the Fountain lua filter on your system
4. Adding the following to config.rb:

fountain_lua = '/path/to/.pandoc/filters/fountain.lua'
require 'pandoc-ruby'
Gollum::Markup.register(
    :fountain, "Fountain", :extensions => ['fountain'],
    :enabled => Gollum::MarkupRegisterUtils::gem_exists?('pandoc-ruby'),
    :render => proc {|content| ::PandocRuby.convert(content, f: fountain_lua, to: :html) } # Note: support for the `:render =>` option requires gollum-lib >= 6.0
)