Improve documentation on Hooks in Jekyll (#8467)
Merge pull request 8467
This commit is contained in:
Ashwin Maroli
GitHub
parent
6dd5bf21b9
commit
e210e337bc
|
|
@ -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 <code>:site</code>, <code>:pages</code>,
|
||||
<code>:posts</code>, <code>:documents</code> and <code>:clean</code>. 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:
|
||||
|
||||
<div class="mobile-side-scroller">
|
||||
<table>
|
||||
<table id="builtin-hooks">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Container</th>
|
||||
<th>Owner</th>
|
||||
<th>Event</th>
|
||||
<th>Called</th>
|
||||
<th>Triggered at</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<td rowspan="6">
|
||||
<p><code>:site</code></p>
|
||||
<p>Encompasses the entire site</p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:after_init</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>Just after the site initializes, but before setup & render. Good
|
||||
for modifying the configuration of the site.</p>
|
||||
<p>Just after the site initializes. Good for modifying the configuration of the site. Triggered once per build / serve session</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:site</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:after_reset</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>Just after site reset</p>
|
||||
<p>Just after the site resets during regeneration</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:site</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:post_read</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>After site data has been read and loaded from disk</p>
|
||||
<p>After all source files have been read and loaded from disk</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:site</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:pre_render</code></p>
|
||||
</td>
|
||||
|
|
@ -86,9 +80,6 @@ The complete list of available hooks is below:
|
|||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:site</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:post_render</code></p>
|
||||
</td>
|
||||
|
|
@ -97,19 +88,17 @@ The complete list of available hooks is below:
|
|||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:site</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:post_write</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>After writing the whole site to disk</p>
|
||||
<p>After writing all of the rendered files to disk</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<td rowspan="5">
|
||||
<p><code>:pages</code></p>
|
||||
<p>Allows fine-grained control over all pages in the site</p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:post_init</code></p>
|
||||
|
|
@ -119,9 +108,6 @@ The complete list of available hooks is below:
|
|||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:pages</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:pre_render</code></p>
|
||||
</td>
|
||||
|
|
@ -130,9 +116,6 @@ The complete list of available hooks is below:
|
|||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:pages</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:post_convert</code></p>
|
||||
</td>
|
||||
|
|
@ -141,9 +124,6 @@ The complete list of available hooks is below:
|
|||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:pages</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:post_render</code></p>
|
||||
</td>
|
||||
|
|
@ -152,9 +132,6 @@ The complete list of available hooks is below:
|
|||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:pages</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:post_write</code></p>
|
||||
</td>
|
||||
|
|
@ -163,8 +140,56 @@ The complete list of available hooks is below:
|
|||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowspan="5">
|
||||
<p><code>:documents</code></p>
|
||||
<p>Allows fine-grained control over all documents in the site including posts and documents in user-defined collections</p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:post_init</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>Whenever any document is initialized</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:pre_render</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>Just before rendering a document</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:post_convert</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
After converting the document content, but before rendering the document
|
||||
layout
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:post_render</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>After rendering a document, but before writing it to disk</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:post_write</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>After writing a document to disk</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowspan="5">
|
||||
<p><code>:posts</code></p>
|
||||
<p>Allows fine-grained control over all posts in the site without affecting documents in user-defined collections</p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:post_init</code></p>
|
||||
|
|
@ -174,9 +199,6 @@ The complete list of available hooks is below:
|
|||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:posts</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:pre_render</code></p>
|
||||
</td>
|
||||
|
|
@ -185,20 +207,14 @@ The complete list of available hooks is below:
|
|||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:posts</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:post_convert</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>After converting the post content, but before rendering the post layout</p>
|
||||
<p>After converting the post content, but before rendering the postlayout</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:posts</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:post_render</code></p>
|
||||
</td>
|
||||
|
|
@ -207,9 +223,6 @@ The complete list of available hooks is below:
|
|||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:posts</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:post_write</code></p>
|
||||
</td>
|
||||
|
|
@ -217,64 +230,10 @@ The complete list of available hooks is below:
|
|||
<p>After writing a post to disk</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:documents</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:post_init</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>Whenever a document is initialized</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:documents</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:pre_render</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>Just before rendering a document</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:documents</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:post_convert</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>After converting the document content, but before rendering the document layout</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:documents</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:post_render</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>After rendering a document, but before writing it to disk</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:documents</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:post_write</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>After writing a document to disk</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><code>:clean</code></p>
|
||||
<p>Fine-grained control on the list of obsolete files determined to be deleted during the site's cleanup phase.</p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>:on_obsolete</code></p>
|
||||
|
|
@ -286,3 +245,45 @@ The complete list of available hooks is below:
|
|||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
## 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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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 {
|
||||
|
|
|
|||
Loading…
Reference in New Issue