Jekyll Compatibility

The original goal was to write a drop-in replacement for Jekyll which would generate identical output, as it would make migration easier and allow jumping back to Jekyll, should there be any unforeseen issues.

Unfortunately there seems to be no canonical list of public API that templates and plug-ins are allowed to access, the rules for variable expansion in permalinks are arcane, so hard to replicate, and the plug-in system, where third party code is called at arbitrary times and allowed to mess around with the program’s private data, does not allow for parallelized building of the site nor lazy evaluation when serving the site.

Nonetheless, we do offer pretty good compatibility, the next sections will go over the various aspects.

Configuration

The _config.yml file is read with most options supported, though if you want to change the markdown converter from the default kramdown then you will need to create a Glim::Filter subclass, for example to change to MultiMarkdown use:

require 'rmultimarkdown'

class CustomMarkdown < Glim::Filter
  transforms 'markdown' => 'html'

  def transform(content, page, options)
    MultiMarkdown.new("\n" + content, "snippet", "no_metadata").to_html
  end
end

The default markdown filter has low priority, so anything that transforms markdown will eclipse it.

Plug-ins

Glim will load plug-ins specified in the configuration file, the Gemfile’s glim_plugins group, or present in any of the plugins directories.

Whether they work is another question. Jekyll has 6 types of plugins:

• Tags: These should generally work assuming no undocumented Jekyll API is accessed.

• Filters: Same as for tags, these should work as long as no undocumented Jekyll API is accessed.

• Converters: These are not used because Glim has a different filter system that require converters to explicitly list the formats that they can convert (so that Glim can intelligently pick the correct filters). It should however be possible to write a Glim::Filter subclass that make use of an existing Jekyll converter, as we currently do for Sass, but it’s probably best to write a native filter.

• Generators: There is a good chance that these will fail, as many generators make assumptions about Jekyll’s internal structure, especially if they add new pages, as there is no canonical way to do that.

  If however the generator can limit itself to using documented API, like iterating the various collections and accessing content or front matter, they should work.

  The generate method will be called after all front matter has been loaded, but before any content creation, and may be called again, incase Glim is running in serve mode, where it will need to re-generate pages after disk changes.

  Support for generators is likely to be removed since their design is problematic for parallelized and lazy building.

• Commands: These are loaded and initialized (init_with_program).

• Hooks: We implement the API to avoid run-time exceptions when loading these but we never invoke any of the hooks.