W3cubDocs

/Jekyll 4

Converters

If you have a new markup language you’d like to use with your site, you can include it by implementing your own converter. Both the Markdown and Textile markup languages are implemented using this method.

Remember your Front Matter

Jekyll will only convert files that have a YAML header at the top, even for converters you add using a plugin.

Below is a converter that will take all posts ending in .upcase and process them using the UpcaseConverter:

module Jekyll
  class UpcaseConverter < Converter
    safe true
    priority :low

    def matches(ext)
      ext =~ /^\.upcase$/i
    end

    def output_ext(ext)
      ".html"
    end

    def convert(content)
      content.upcase
    end
  end
end

Converters should implement at a minimum 3 methods:

Method	Description
`matches`	Does the given extension match this converter’s list of acceptable extensions? Takes one argument: the file’s extension (including the dot). Must return `true` if it matches, `false` otherwise.
`output_ext`	The extension to be given to the output file (including the dot). Usually this will be `".html"`.
`convert`	Logic to do the content conversion. Takes one argument: the raw content of the file (without front matter). Must return a String.

In our example, UpcaseConverter#matches checks if our filename extension is .upcase, and will render using the converter if it is. It will call UpcaseConverter#convert to process the content. In our simple converter we’re simply uppercasing the entire content string. Finally, when it saves the page, it will do so with a .html extension.