Improve this page

Markdown Options

The various Markdown renderers supported by Jekyll sometimes have extra options available.

Kramdown

Kramdown is the default Markdown renderer for Jekyll, and often works well with no additional configuration. However, it does support many configuration options.

Kramdown Processor

By default, Jekyll uses the GitHub Flavored Markdown (GFM) processor for Kramdown. (Specifying input: GFM is fine, but redundant.) GFM supports a couple additional Kramdown options, documented by kramdown-parser-gfm. These options can be used directly in your Kramdown Jekyll config, like this:

kramdown:
  gfm_quirks: [paragraph_end]

You can also change the processor used by Kramdown (as specified for the input key in the Kramdown RDoc). For example, to use the non-GFM Kramdown processor in Jekyll, add the following to your configuration.

kramdown:
  input: Kramdown

Documentation for Kramdown parsers is available in the Kramdown docs. If you use a Kramdown parser other than Kramdown or GFM, you’ll need to add the gem for it.

Syntax Highlighting (CodeRay)

To use the CodeRay syntax highlighter with Kramdown, you need to add a dependency on the kramdown-syntax-coderay gem. For example, bundle add kramdown-syntax-coderay. Then, you’ll be able to specify CodeRay in your syntax_highlighter config:

kramdown:
  syntax_highlighter: coderay

CodeRay supports several of its own configuration options, documented in the kramdown-syntax-coderay docs which can be passed as syntax_highlighter_opts like this:

kramdown:
  syntax_highlighter: coderay
  syntax_highlighter_opts:
    line_numbers: table
    bold_every: 5

Advanced Kramdown Options

Kramdown supports a variety of other relatively advanced options such as header_offset and smart_quotes. These are documented in the Kramdown configuration documentation and can be added to your Kramdown config like this:

kramdown:
  header_offset: 2

There are several unsupported kramdown options

Please note that Jekyll uses Kramdown's HTML converter. Kramdown options used only by other converters, such as remove_block_html_tags (used by the RemoveHtmlTags converter), will not work.

CommonMark

CommonMark is a rationalized version of Markdown syntax, implemented in C and thus faster than default Kramdown implemented in Ruby. It slightly differs from original Markdown and does not support all the syntax elements implemented in Kramdown, like Block Inline Attribute Lists.

It comes in two flavors: basic CommonMark with jekyll-commonmark plugin and GitHub Flavored Markdown supported by GitHub Pages.

Custom Markdown Processors

If you’re interested in creating a custom markdown processor, you’re in luck! Create a new class in the Jekyll::Converters::Markdown namespace:

class Jekyll::Converters::Markdown::MyCustomProcessor
  def initialize(config)
    require 'funky_markdown'
    @config = config
  rescue LoadError
    STDERR.puts 'You are missing a library required for Markdown. Please run:'
    STDERR.puts '  $ [sudo] gem install funky_markdown'
    raise FatalException.new("Missing dependency: funky_markdown")
  end

  def convert(content)
    ::FunkyMarkdown.new(content).convert
  end
end

Once you’ve created your class and have it properly set up either as a plugin in the _plugins folder or as a gem, specify it in your _config.yml:

markdown: MyCustomProcessor