entry one
}}}}}" in "_site/2015/03/14/entry1.html" + + Scenario: Allow hooks to have a named priority + Given I have a _plugins directory + And I have a "_plugins/ext.rb" file with content: + """ + Jekyll::Hooks.register :page, :post_render, priority: :normal do |owner| + # first normal runs second + owner.output = "1 #{owner.output.chomp}" + end + Jekyll::Hooks.register :page, :post_render, priority: :high do |owner| + # high runs last + owner.output = "2 #{owner.output.chomp}" + end + Jekyll::Hooks.register :page, :post_render do |owner| + # second normal runs third (normal is default) + owner.output = "3 #{owner.output.chomp}" + end + Jekyll::Hooks.register :page, :post_render, priority: :low do |owner| + # low runs first + owner.output = "4 #{owner.output.chomp}" + end + """ + And I have a "index.html" page that contains "WRAP ME" + When I run jekyll build + Then I should see "2 3 1 4 WRAP ME" in "_site/index.html" + + Scenario: Alter a document right after it is initialized + Given I have a _plugins directory + And I have a "_plugins/ext.rb" file with content: + """ + Jekyll::Hooks.register :document, :pre_render do |doc, payload| + doc.data['text'] = doc.data['text'] << ' are belong to us' + end + """ + And I have a "_config.yml" file that contains "collections: [ memes ]" + And I have a _memes directory + And I have a "_memes/doc1.md" file with content: + """ + --- + text: all your base + --- + """ + And I have an "index.md" file with content: + """ + --- + --- + {{ site.memes.first.text }} + """ + When I run jekyll build + Then the _site directory should exist + And I should see "all your base are belong to us" in "_site/index.html" + + Scenario: Update a document after rendering it, but before writing it to disk + Given I have a _plugins directory + And I have a "_plugins/ext.rb" file with content: + """ + Jekyll::Hooks.register :document, :post_render do |doc| + doc.output.gsub! //, '
' + end + """ + And I have a "_config.yml" file with content: + """ + collections: + memes: + output: true + """ + And I have a _memes directory + And I have a "_memes/doc1.md" file with content: + """ + --- + text: all your base are belong to us + --- + {{ page.text }} + """ + When I run jekyll build + Then the _site directory should exist + And I should see "
all your base are belong to us" in "_site/memes/doc1.html" + + Scenario: Perform an action after every document is written + Given I have a _plugins directory + And I have a "_plugins/ext.rb" file with content: + """ + Jekyll::Hooks.register :document, :post_write do |doc| + open('_site/document-build.log', 'a') do |f| + f.puts "Wrote document #{doc.collection.docs.index doc} at #{Time.now}" + end + end + """ + And I have a "_config.yml" file with content: + """ + collections: + memes: + output: true + """ + And I have a _memes directory + And I have a "_memes/doc1.md" file with content: + """ + --- + text: all your base are belong to us + --- + {{ page.text }} + """ + When I run jekyll build + Then the _site directory should exist + And I should see "Wrote document 0" in "_site/document-build.log" diff --git a/lib/jekyll.rb b/lib/jekyll.rb index 7506553a..58eda759 100644 --- a/lib/jekyll.rb +++ b/lib/jekyll.rb @@ -48,6 +48,7 @@ module Jekyll autoload :External, 'jekyll/external' autoload :Filters, 'jekyll/filters' autoload :FrontmatterDefaults, 'jekyll/frontmatter_defaults' + autoload :Hooks, 'jekyll/hooks' autoload :Layout, 'jekyll/layout' autoload :CollectionReader, 'jekyll/readers/collection_reader' autoload :DataReader, 'jekyll/readers/data_reader' diff --git a/lib/jekyll/convertible.rb b/lib/jekyll/convertible.rb index fdbf3e85..5767ab02 100644 --- a/lib/jekyll/convertible.rb +++ b/lib/jekyll/convertible.rb @@ -236,6 +236,7 @@ module Jekyll # # Returns nothing. def do_layout(payload, layouts) + Jekyll::Hooks.trigger self, :pre_render, payload info = { :filters => [Jekyll::Filters], :registers => { :site => site, :page => payload['page'] } } # render and transform content (this becomes the final content of the object) @@ -249,6 +250,7 @@ module Jekyll self.output = content render_all_layouts(layouts, payload, info) if place_in_layout? + Jekyll::Hooks.trigger self, :post_render end # Write the generated page file to the destination directory. @@ -262,6 +264,7 @@ module Jekyll File.open(path, 'wb') do |f| f.write(output) end + Jekyll::Hooks.trigger self, :post_write end # Accessor for data properties by Liquid. diff --git a/lib/jekyll/document.rb b/lib/jekyll/document.rb index 9cf9ce12..045bdacb 100644 --- a/lib/jekyll/document.rb +++ b/lib/jekyll/document.rb @@ -189,6 +189,8 @@ module Jekyll File.open(path, 'wb') do |f| f.write(output) end + + Jekyll::Hooks.trigger self, :post_write end # Returns merged option hash for File.read of self.site (if exists) diff --git a/lib/jekyll/hooks.rb b/lib/jekyll/hooks.rb new file mode 100644 index 00000000..d01cae4c --- /dev/null +++ b/lib/jekyll/hooks.rb @@ -0,0 +1,107 @@ +module Jekyll + module Hooks + # Helps look up hooks from the registry by owner's class + OWNER_MAP = { + Jekyll::Site => :site, + Jekyll::Page => :page, + Jekyll::Post => :post, + Jekyll::Document => :document, + }.freeze + + DEFAULT_PRIORITY = 20 + + # compatibility layer for octopress-hooks users + PRIORITY_MAP = { + low: 10, + normal: 20, + high: 30, + }.freeze + + # initial empty hooks + @registry = { + :site => { + after_reset: [], + post_read: [], + pre_render: [], + post_write: [], + }, + :page => { + post_init: [], + pre_render: [], + post_render: [], + post_write: [], + }, + :post => { + post_init: [], + pre_render: [], + post_render: [], + post_write: [], + }, + :document => { + pre_render: [], + post_render: [], + post_write: [], + }, + } + + # map of all hooks and their priorities + @hook_priority = {} + + NotAvailable = Class.new(RuntimeError) + Uncallable = Class.new(RuntimeError) + + # register hook(s) to be called later, public API + def self.register(owners, event, priority: DEFAULT_PRIORITY, &block) + Array(owners).each do |owner| + register_one(owner, event, priority_value(priority), &block) + end + end + + # Ensure the priority is a Fixnum + def self.priority_value(priority) + return priority if priority.is_a?(Fixnum) + PRIORITY_MAP[priority] || DEFAULT_PRIORITY + end + + # register a single hook to be called later, internal API + def self.register_one(owner, event, priority, &block) + unless @registry[owner] + raise NotAvailable, "Hooks are only available for the following " << + "classes: #{@registry.keys.inspect}" + end + + unless @registry[owner][event] + raise NotAvailable, "Invalid hook. #{owner} supports only the " << + "following hooks #{@registry[owner].keys.inspect}" + end + + unless block.respond_to? :call + raise Uncallable, "Hooks must respond to :call" + end + + insert_hook owner, event, priority, &block + end + + def self.insert_hook(owner, event, priority, &block) + @hook_priority[block] = "#{priority}.#{@hook_priority.size}".to_f + @registry[owner][event] << block + end + + # interface for Jekyll core components to trigger hooks + def self.trigger(instance, event, *args) + owner_symbol = OWNER_MAP[instance.class] + + # proceed only if there are hooks to call + return unless @registry[owner_symbol] + return unless @registry[owner_symbol][event] + + # hooks to call for this owner and event + hooks = @registry[owner_symbol][event] + + # sort and call hooks according to priority and load order + hooks.sort_by { |h| @hook_priority[h] }.each do |hook| + hook.call(instance, *args) + end + end + end +end diff --git a/lib/jekyll/page.rb b/lib/jekyll/page.rb index 36b12aa1..f9040da8 100644 --- a/lib/jekyll/page.rb +++ b/lib/jekyll/page.rb @@ -35,6 +35,8 @@ module Jekyll data.default_proc = proc do |hash, key| site.frontmatter_defaults.find(File.join(dir, name), type, key) end + + Jekyll::Hooks.trigger self, :post_init end # The generated directory into which the page will be placed diff --git a/lib/jekyll/post.rb b/lib/jekyll/post.rb index 780f40f7..252cca42 100644 --- a/lib/jekyll/post.rb +++ b/lib/jekyll/post.rb @@ -68,6 +68,8 @@ module Jekyll populate_categories populate_tags + + Jekyll::Hooks.trigger self, :post_init end def published? diff --git a/lib/jekyll/renderer.rb b/lib/jekyll/renderer.rb index f25ca343..4a772978 100644 --- a/lib/jekyll/renderer.rb +++ b/lib/jekyll/renderer.rb @@ -35,6 +35,8 @@ module Jekyll "page" => document.to_liquid }, site_payload || site.site_payload) + Jekyll::Hooks.trigger document, :pre_render, payload + info = { filters: [Jekyll::Filters], registers: { :site => site, :page => payload['page'] } diff --git a/lib/jekyll/site.rb b/lib/jekyll/site.rb index 92aa0f39..e7307bbf 100644 --- a/lib/jekyll/site.rb +++ b/lib/jekyll/site.rb @@ -75,6 +75,8 @@ module Jekyll if limit_posts < 0 raise ArgumentError, "limit_posts must be a non-negative number" end + + Jekyll::Hooks.trigger self, :after_reset end # Load necessary libraries, plugins, converters, and generators. @@ -132,6 +134,7 @@ module Jekyll def read reader.read limit_posts! + Jekyll::Hooks.trigger self, :post_read end # Run each of the Generators. @@ -150,15 +153,18 @@ module Jekyll relative_permalinks_are_deprecated payload = site_payload + + Jekyll::Hooks.trigger self, :pre_render, payload + collections.each do |label, collection| collection.docs.each do |document| if regenerator.regenerate?(document) document.output = Jekyll::Renderer.new(self, document, payload).run + Jekyll::Hooks.trigger document, :post_render end end end - payload = site_payload [posts, pages].flatten.each do |page_or_post| if regenerator.regenerate?(page_or_post) page_or_post.render(layouts, payload) @@ -183,6 +189,7 @@ module Jekyll item.write(dest) if regenerator.regenerate?(item) } regenerator.write_metadata + Jekyll::Hooks.trigger self, :post_write end # Construct a Hash of Posts indexed by the specified Post attribute. diff --git a/site/_docs/plugins.md b/site/_docs/plugins.md index 03357c44..54830623 100644 --- a/site/_docs/plugins.md +++ b/site/_docs/plugins.md @@ -470,6 +470,220 @@ module Jekyll end {% endhighlight %} +## Hooks + +
+ In order to use this feature, + install the latest development version of Jekyll. +
+:site, :page,
+:post, and :document. In all cases, Jekyll calls your
+hooks with the container object as the first callback parameter. But in the
+case of :pre_render, your hook will also receive a payload hash as
+a second parameter which allows you full control over the variables that are
+available while rendering.
+
+The complete list of available hooks is below:
+
+| Container | +Event | +Called | +
|---|---|---|
|
+
|
+
+
|
+
+ Just after site reset + |
+
|
+
|
+
+
|
+
+ Just before rendering the whole site + |
+
|
+
|
+
+
|
+
+ After rendering the whole site, but before writing any files + |
+
|
+
|
+
+
|
+
+ After writing the whole site to disk + |
+
|
+
|
+
+
|
+
+ Whenever a page is initialized + |
+
|
+
|
+
+
|
+
+ Just before rendering a page + |
+
|
+
|
+
+
|
+
+ After rendering a page, but before writing it to disk + |
+
|
+
|
+
+
|
+
+ After writing a page to disk + |
+
|
+
|
+
+
|
+
+ Whenever a post is initialized + |
+
|
+
|
+
+
|
+
+ Just before rendering a post + |
+
|
+
|
+
+
|
+
+ After rendering a post, but before writing it to disk + |
+
|
+
|
+
+
|
+
+ After writing a post to disk + |
+
|
+
|
+
+
|
+
+ Just before rendering a document + |
+
|
+
|
+
+
|
+
+ After rendering a document, but before writing it to disk + |
+
|
+
|
+
+
|
+
+ After writing a document to disk + |
+