Improve documentation on Hooks in Jekyll (#8467)

Merge pull request 8467

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
+Using hooks, your plugin can exercise fine-grained control over various aspects of the build process. If your plugin defines any hooks, Jekyll
-of the build process. If your plugin defines any hooks, Jekyll will call them
+will call them at pre-defined points.
-at pre-defined points.
 
-Hooks are registered to a container and an event name. To register one, you
+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,
-call Jekyll::Hooks.register, and pass the container, event name, and code to
+and code to call whenever the hook is triggered. For example, if you want to execute some custom functionality every time Jekyll renders a
-call whenever the hook is triggered. For example, if you want to execute some
+page, you could register a hook like this:
-custom functionality every time Jekyll renders a post, you could register a
-hook like this:
 
 ```ruby
-Jekyll::Hooks.register :posts, :post_render do |post|
+Jekyll::Hooks.register :pages, :post_render do |page|
-  # code to call after Jekyll renders a post
+  # code to call after Jekyll renders a page
 end
 ```
 
-Jekyll provides hooks for <code>:site</code>, <code>:pages</code>,
+*Note: The `:post_convert` events mentioned hereafter is a feature introduced in v4.2.0.*
-<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).
 
-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 &mdash; `:post_init`, `:pre_render`, `:post_convert`, `:post_render`, `:post_write`
+&mdash; 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
+        <p>Just after the site initializes. Good for modifying the configuration of the site. Triggered once per build / serve session</p>
-        for modifying the configuration of the site.</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,9 +207,6 @@ 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>
@@ -196,9 +215,6 @@ The complete list of available hooks is below:
       </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
+```

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 {