octopress-hooks

Octopress Hooks

Modify Jekyll's Site, Pages and Posts at different points during the site processing stream.

Installation

Add this line to your application's Gemfile:

gem 'octopress-hooks'

And then execute:

$ bundle

Or install it yourself as:

$ gem install octopress-hooks

Hook timeline

This is the order in which hooks are triggered.

• Site reset
• Site pre_read
• Site post_read
• Post/Page/Document post_init
• Site pre_render
• Site merge_payload
• Post/Page/Document pre_render
• Post/Page/Document merge_payload
• Post/Page/Document post_render
• Post/Page/Document post_write
• Site post_write

Usage

First extend the appropriate Hook class.

• Octopress::Hooks::Site - access Jekyll's Site instance.
• Octopress::Hooks::Page - access to each of Jekyll's Page instances.
• Octopress::Hooks::Post - access to each of Jekyll's Post instances.
• Octopress::Hooks::Document - access to each of Jekyll's Collection Documents instances.

Then add a method based on when you want to trigger your hooks.

Site Hooks

The Site class has three methods. Here's an example.

class MySiteHook < Octopress::Hooks::Site
  def reset(site)
  end
  
  def pre_read(site)
  end

  def post_read(site)
  end

  def pre_render(site)
  end

  # Return a hash to merge into payload
  #
  def merge_payload(payload, site)
    {}
  end

  def post_write(site)
  end
end

Use the reset hook to reset variables to before each build. It's mostly useful to support --watch builds.

Use the pre_read hook to modify the site instance before posts, pages and static files are read.

Use the post_read hook to modify the site instance after posts, pages and static files are read but before generators are triggered.

Use the pre_render hook to modify the site instance before posts and pages are rendered.

Use the merge_payload hook to modify the site payload or merge custom data into it. This data will be available to all documents when they are rendered. This method must return a hash.

Use the post_write to trigger and action after all documents have been written to disk.

Post/Page/Documents hooks

The Page, Post and Document hooks have four methods and are identical except that Post hooks only operate on posts, and Page hooks only operate on pages and Document hooks only Operate on Collection Documents. Here's an example of a Page hook.

class MyPageHook < Octopress::Hooks::Page

  def post_init(page)
  end
  
  def pre_render(page)
  end

  # Return a hash to merge into payload
  #
  def merge_payload(payload, page)
    {}
  end

  def post_render(page)
  end

  def post_write(page)
  end
end

The post_init method lets you access the post or page class instance immediately after it has been initialized. This allows you to modify the instance before the Site compiles its payload, which includes arrays of each page and post.

With pre_render you can parse and modify page contents before it is processed by Liquid, Markdown, Textile and the like, and rendered to HTML.

Use the merge_paylod hook to modify the page and site payload or merge custom data into it. Changes to the payload will only affect this page when it is rendered. This method must return a hash to be merged.

With post_render you can access pages and posts after it has been converted into HTML. You might use this option if you want to modify generated HTML. At this stage, be sure to modify the page.output if you want change what the page displays.

With post_write you can execute a code block after a page or post has been successfully written to disk.

To work with all page types, you'd do something like this.

module Toaster
  class ProcessAll < Octopress::Hooks::All
    def pre_render(item)
      item.content.gsub!(/bread/, 'toast')
    end
  end
end

To process pages, posts, or documents individually, you'd do this.

module Samurai
  class ProcessPosts < Octopress::Hooks::Post
    def pre_render(post)
      post.gsub!(/bread/, 'sliced bread')
    end
  end

  class ProcessPages < Octopress::Hooks::Page
    def pre_render(page)
      post.gsub!(/bread/, 'sliced bread')
    end
  end

  class ProcessPages < Octopress::Hooks::Document
    def pre_render(page)
      post.gsub!(/bread/, 'sliced bread')
    end
  end
end

Contributing

• Fork it ( https://github.com/octopress/hooks/fork )
• Create your feature branch (git checkout -b my-new-feature)
• Commit your changes (git commit -am 'Add some feature')
• Push to the branch (git push origin my-new-feature)
• Create a new Pull Request