diff --git a/docs/_docs/plugins/hooks.md b/docs/_docs/plugins/hooks.md index 413ecdec..58b750ca 100644 --- a/docs/_docs/plugins/hooks.md +++ b/docs/_docs/plugins/hooks.md @@ -3,81 +3,75 @@ title: Hooks permalink: /docs/plugins/hooks/ --- -Using hooks, your plugin can exercise fine-grained control over various aspects -of the build process. If your plugin defines any hooks, Jekyll will call them -at pre-defined points. +Using hooks, your plugin can exercise fine-grained control over various aspects of the build process. If your plugin defines any hooks, Jekyll +will call them at pre-defined points. -Hooks are registered to a container and an event name. To register one, you -call Jekyll::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 Jekyll renders a post, you could register a -hook like this: +Hooks are registered to an owner and an event name. To register one, you call `Jekyll::Hooks.register`, and pass the hook owner, event name, +and code to call whenever the hook is triggered. For example, if you want to execute some custom functionality every time Jekyll renders a +page, you could register a hook like this: ```ruby -Jekyll::Hooks.register :posts, :post_render do |post| - # code to call after Jekyll renders a post +Jekyll::Hooks.register :pages, :post_render do |page| + # code to call after Jekyll renders a page end ``` -Jekyll provides hooks for :site, :pages, -:posts, :documents and :clean. In all -cases, Jekyll calls your hooks with the container object as the first callback -parameter. 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). +*Note: The `:post_convert` events mentioned hereafter is a feature introduced in v4.2.0.* -The complete list of available hooks is below: +Out of the box, Jekyll has pre-defined hook points for owners `:site`, `:pages`, `:documents` and `:clean`. Additionally, the hook points +defined for `:documents` can be utilized for individual collections only by invoking the collection type instead. i.e. `:posts` for documents +in collection `_posts` and `:movies` for documents in collection `_movies`. In all cases, Jekyll calls your hooks with the owner object as the +first callback parameter. + +Every registered hook owner supports the following events — `:post_init`, `:pre_render`, `:post_convert`, `:post_render`, `:post_write` +— however, the `:site` owner is set up to *respond* to *special event names*. Refer to the subsequent section for details. + +All `:pre_render` hooks and the `:site, :post_render` hook will also provide a `payload` hash as a second parameter. While in the case of +`:pre_render` events, the payload gives you full control over the variables that are available during rendering, with the `:site, :post_render` +event, the payload contains final values after rendering all the site (useful for sitemaps, feeds, etc). + +## Built-in Hook Owners and Events +The complete list of available hooks:
- +
- + - + - - - - @@ -86,9 +80,6 @@ The complete list of available hooks is below: - @@ -97,19 +88,17 @@ The complete list of available hooks is below: - - - @@ -130,9 +116,6 @@ The complete list of available hooks is below: - @@ -141,9 +124,6 @@ The complete list of available hooks is below: - @@ -152,9 +132,6 @@ The complete list of available hooks is below: - @@ -163,8 +140,56 @@ The complete list of available hooks is below: + + + + + + + + + + + + + + + + + + + + + - @@ -185,20 +207,14 @@ The complete list of available hooks is below: - - @@ -207,9 +223,6 @@ The complete list of available hooks is below: - @@ -217,64 +230,10 @@ The complete list of available hooks is below:

After writing a post to disk

- - - - - - - - - - - - - - - - - - - - - - - - -
ContainerOwner EventCalledTriggered at
+

:site

+

Encompasses the entire site

:after_init

-

Just after the site initializes, but before setup & render. Good - for modifying the configuration of the site.

+

Just after the site initializes. Good for modifying the configuration of the site. Triggered once per build / serve session

-

:site

-

:after_reset

-

Just after site reset

+

Just after the site resets during regeneration

-

:site

-

:post_read

-

After site data has been read and loaded from disk

+

After all source files have been read and loaded from disk

-

:site

-

:pre_render

-

:site

-

:post_render

-

:site

-

:post_write

-

After writing the whole site to disk

+

After writing all of the rendered files to disk

+

:pages

+

Allows fine-grained control over all pages in the site

:post_init

@@ -119,9 +108,6 @@ The complete list of available hooks is below:
-

:pages

-

:pre_render

-

:pages

-

:post_convert

-

:pages

-

:post_render

-

:pages

-

:post_write

+

:documents

+

Allows fine-grained control over all documents in the site including posts and documents in user-defined collections

+
+

:post_init

+
+

Whenever any document is initialized

+
+

:pre_render

+
+

Just before rendering a document

+
+

:post_convert

+
+

+ After converting the document content, but before rendering the document + layout +

+
+

:post_render

+
+

After rendering a document, but before writing it to disk

+
+

:post_write

+
+

After writing a document to disk

+

:posts

+

Allows fine-grained control over all posts in the site without affecting documents in user-defined collections

:post_init

@@ -174,9 +199,6 @@ The complete list of available hooks is below:
-

:posts

-

:pre_render

-

:posts

-

:post_convert

-

After converting the post content, but before rendering the post layout

+

After converting the post content, but before rendering the postlayout

-

:posts

-

:post_render

-

:posts

-

:post_write

-

:documents

-
-

:post_init

-
-

Whenever a document is initialized

-
-

:documents

-
-

:pre_render

-
-

Just before rendering a document

-
-

:documents

-
-

:post_convert

-
-

After converting the document content, but before rendering the document layout

-
-

:documents

-
-

:post_render

-
-

After rendering a document, but before writing it to disk

-
-

:documents

-
-

:post_write

-
-

After writing a document to disk

-

:clean

+

Fine-grained control on the list of obsolete files determined to be deleted during the site's cleanup phase.

:on_obsolete

@@ -286,3 +245,45 @@ The complete list of available hooks is below:
+ +## Hooks for custom Jekyll objects + +You can also register and trigger hooks for Jekyll objects introduced by your plugin. All it takes is placing `trigger` calls under a suitable +`owner` name, at positons desired within your custom class and registering the `owner` by your plugin. + +To illustrate, consider the following plugin that implements custom functionality for every custom `Excerpt` object initialized: + +```ruby +module Foobar + class HookedExcerpt < Jekyll::Excerpt + def initialize(doc) + super + trigger_hooks(:post_init) + end + + def output + @output ||= trigger_hooks(:post_render, renderer.run) + end + + def renderer + @renderer ||= Jekyll::Renderer.new( + doc.site, self, site.site_payload + ) + end + + def trigger_hooks(hook_name, *args) + Jekyll::Hooks.trigger :excerpts, hook_name, self, *args + end + end +end + +Jekyll::Hooks.register :excerpts, :post_init do |excerpt| + Jekyll.logger.debug "Initialized:", + "Hooked Excerpt for #{excerpt.doc.inspect}" +end + +Jekyll::Hooks.register :excerpts, :post_render do |excerpt, output| + return output unless excerpt.doc.type == :posts + Foobar.transform(output) +end +``` diff --git a/docs/_sass/_style.scss b/docs/_sass/_style.scss index 9e3ca1c8..599c6480 100644 --- a/docs/_sass/_style.scss +++ b/docs/_sass/_style.scss @@ -966,6 +966,15 @@ code.output { margin-bottom: 2px; } +table#builtin-hooks { + td { + text-align: center; + &:first-of-type { + max-width: 330px + } + } +} + /* Note types */ .note {