Formats and extensions - tttaaaa/gollum GitHub Wiki

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.

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

{
    # primary-extension => { markup-name, markup-file-extension-regex }

    :markdown => { :name => "Markdown", :regexp => /md|mkdn?|mdown|markdown/ },
    :textile => { :name => "Textile", :regexp => /textile/ },
    :rdoc => { :name => "RDoc", :regexp => /rdoc/ },
    :org => { :name => "Org-mode", :regexp => /org/ },
    :creole => { :name => "Creole", :regexp => /creole/ },
    :rest => { :name => "reStructuredText", :regexp => /re?st(\.txt)?/ },
    :asciidoc => { :name => "AsciiDoc", :regexp => /asciidoc/ },
    :mediawiki => { :name => "MediaWiki", :regexp => /(media)?wiki/ },
    :pod => { :name => "Pod", :regexp => /pod/ },
    :txt => { :name => "Plain Text", :regexp => /txt/ }
}

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

The following chapters will show how to customize this configuration. All of the provided examples can easily be combined. In case you’re starting Gollum via Rack, simply ignore the --config and config.rb remarks and put the code into config.ru.

Setting primary extension for a markup (e.g. AsciiDoc)

Start Gollum with the --config option and put the following into your config.rb file:

# always include this:
Gollum::Page.send :remove_const, :FORMAT_NAMES if defined? Gollum::Page::FORMAT_NAMES

# remove the original AsciiDoc binding:
Gollum::Markup.formats.delete(:asciidoc)

# and define your own (".asc" is the new primary extension):
Gollum::Markup.formats[:asc] = {
    :name => "AsciiDoc",
    :regexp => /asciidoc/
}

Customizing extensions bound to a markup (e.g. AsciiDoc)

Start Gollum with the --config option and put the following into your config.rb file:

# always include this:
Gollum::Page.send :remove_const, :FORMAT_NAMES if defined? Gollum::Page::FORMAT_NAMES

# bind your own extension regex (the new set of extensions will also include `.asc` and `.adoc`):
Gollum::Markup.formats[:asciidoc][:regexp] = /(?:asciidoc|asc|adoc)/

Limiting supported formats (e.g. only to AsciiDoc)

Start Gollum with the --config option and put the following into your config.rb file:

# always include this:
Gollum::Page.send :remove_const, :FORMAT_NAMES if defined? Gollum::Page::FORMAT_NAMES

# first remove all markups:
Gollum::Markup.formats.clear

# and then define the sole markup to be supported:
Gollum::Markup.formats[:asciidoc] = {
    :name => "AsciiDoc",
    :regexp => /asciidoc/
}

Changing github-markup’s default renderings settings (e.g., turning asciidoctor’s safe mode on)

GitHub::Markup.markups.reject! {|markup| markup.regexp.to_s == '(?-mix:adoc|asc(iidoc)?)' }

GitHub::Markup.markup(:asciidoctor, /adoc|asc(iidoc)?/) do |content|
  Asciidoctor::Compliance.unique_id_start_index = 1
  Asciidoctor.convert(content, :safe => :safe, :attributes => %w(showtitle=@ idprefix idseparator=- env=github env-github source-highlighter=html-pipeline))
end
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️