Plugins

Bunto has a plugin system with hooks that allow you to create custom generated content specific to your site. You can run custom code for your site without having to modify the Bunto source itself.

Installing a plugin

You have 3 options for installing plugins:

1. In your site source root, make a _plugins directory. Place your plugins here. Any file ending in *.rb inside this directory will be loaded before Bunto generates your site.

2. In your _config.yml file, add a new array with the key gems and the values of the gem names of the plugins you’d like to use. An example:

    gems: [bunto-coffeescript, bunto-watch, bunto-assets]
    # This will require each of these gems automatically.
   

   Then install your plugins using gem install bunto-coffeescript bunto-watch bunto-assets

3. Add the relevant plugins to a Bundler group in your Gemfile. An example:

    group :bunto_plugins do
      gem "my-bunto-plugin"
      gem "another-bunto-plugin"
    end
   

   Now you need to install all plugins from your Bundler group by running single command bundle install

In general, plugins you make will fall into one of five categories:

1. Generators
2. Converters
3. Commands
4. Tags
5. Hooks

Generators

You can create a generator when you need Bunto to create additional content based on your own rules.

A generator is a subclass of Bunto::Generator that defines a generate method, which receives an instance of Bunto::Site. The return value of generate is ignored.

Generators run after Bunto has made an inventory of the existing content, and before the site is generated. Pages with YAML Front Matters are stored as instances of Bunto::Page and are available via site.pages. Static files become instances of Bunto::StaticFile and are available via site.static_files. See the Variables documentation page and Bunto::Site for more details.

For instance, a generator can inject values computed at build time for template variables. In the following example the template reading.html has two variables ongoing and done that we fill in the generator:

module Reading
  class Generator < Bunto::Generator
    def generate(site)
      ongoing, done = Book.all.partition(&:ongoing?)

      reading = site.pages.detect {|page| page.name == 'reading.html'}
      reading.data['ongoing'] = ongoing
      reading.data['done'] = done
    end
  end
end

This is a more complex generator that generates new pages:

module Bunto

  class CategoryPage < Page
    def initialize(site, base, dir, category)
      @site = site
      @base = base
      @dir = dir
      @name = 'index.html'

      self.process(@name)
      self.read_yaml(File.join(base, '_layouts'), 'category_index.html')
      self.data['category'] = category

      category_title_prefix = site.config['category_title_prefix'] || 'Category: '
      self.data['title'] = "#{category_title_prefix}#{category}"
    end
  end

  class CategoryPageGenerator < Generator
    safe true

    def generate(site)
      if site.layouts.key? 'category_index'
        dir = site.config['category_dir'] || 'categories'
        site.categories.each_key do |category|
          site.pages << CategoryPage.new(site, site.source, File.join(dir, category), category)
        end
      end
    end
  end

end

In this example, our generator will create a series of files under the categories directory for each category, listing the posts in each category using the category_index.html layout.

Generators are only required to implement one method:

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.

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

module Bunto
  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:

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.

Commands

As of version 2.5.0, Bunto can be extended with plugins which provide subcommands for the bunto executable. This is possible by including the relevant plugins in a Gemfile group called :bunto_plugins:

group :bunto_plugins do
  gem "my_fancy_bunto_plugin"
end

Each Command must be a subclass of the Bunto::Command class and must contain one class method: init_with_program. An example:

class MyNewCommand < Bunto::Command
  class << self
    def init_with_program(prog)
      prog.command(:new) do |c|
        c.syntax "new [options]"
        c.description 'Create a new Bunto site.'

        c.option 'dest', '-d DEST', 'Where the site should go.'

        c.action do |args, options|
          Bunto::Site.new_site_at(options['dest'])
        end
      end
    end
  end
end

Commands should implement this single class method:

Tags

If you’d like to include custom liquid tags in your site, you can do so by hooking into the tagging system. Built-in examples added by Bunto include the highlight and include tags. Below is an example of a custom liquid tag that will output the time the page was rendered:

module Bunto
  class RenderTimeTag < Liquid::Tag

    def initialize(tag_name, text, tokens)
      super
      @text = text
    end

    def render(context)
      "#{@text} #{Time.now}"
    end
  end
end

Liquid::Template.register_tag('render_time', Bunto::RenderTimeTag)

At a minimum, liquid tags must implement:

You must also register the custom tag with the Liquid template engine as follows:

Liquid::Template.register_tag('render_time', Bunto::RenderTimeTag)

In the example above, we can place the following tag anywhere in one of our pages:

<p>{% render_time page rendered at: %}</p>

And we would get something like this on the page:

<p>page rendered at: Tue June 22 23:38:47 –0500 2010</p>

Liquid filters

You can add your own filters to the Liquid template system much like you can add tags above. Filters are simply modules that export their methods to liquid. All methods will have to take at least one parameter which represents the input of the filter. The return value will be the output of the filter.

module Bunto
  module AssetFilter
    def asset_url(input)
      "http://www.example.com/#{input}?#{Time.now.to_i}"
    end
  end
end

Liquid::Template.register_filter(Bunto::AssetFilter)

Flags

There are two flags to be aware of when writing a plugin:

To use one of the example plugins above as an illustration, here is how you’d specify these two flags:

module Bunto
  class UpcaseConverter < Converter
    safe true
    priority :low
    ...
  end
end

Hooks

Using hooks, your plugin can exercise fine-grained control over various aspects of the build process. If your plugin defines any hooks, Bunto will call them at pre-defined points.

Hooks are registered to a container and an event name. To register one, you call Bunto::Hooks.register, and pass the container, event name, and code to call whenever the hook is triggered. For example, if you want to execute some custom functionality every time Bunto renders a post, you could register a hook like this:

Bunto::Hooks.register :posts, :post_render do |post|
  # code to call after Bunto renders a post
end

Bunto provides hooks for :site, :pages, :posts, and :documents. In all cases, Bunto calls your hooks with the container object as the first callback parameter. However, all :pre_render hooks and the:site, :post_render hook will also provide a payload hash as a second parameter. In the case of :pre_render, the payload gives you full control over the variables that are available while rendering. In the case of :site, :post_render, the payload contains final values after rendering all the site (useful for sitemaps, feeds, etc).

The complete list of available hooks is below: