Support hooks for transforming build script output

[Beorn] / README.markdown
diff --git a/README.markdown b/README.markdown

index a0f30435443d0395c67ae446c3d2c4d95060fa1f..6a72afb3e0e4eb075caface925e73317c5948d1a 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -123,7 +123,48 @@ file extension. A sample `.rsync-filter` might be as follows :—
  Feel free to add styles, additional content, and whatever else you like
  to the template files (as well as the rest of the website).
  
  Feel free to add styles, additional content, and whatever else you like
  to the template files (as well as the rest of the website).
  
-To modify what content is generated, simply edit `build.js` :) .
+### Hooks
+
+🧸📔 Bjørn recognizes the following hooks (defined on the global
+object) when it runs :—
+
+- **`globalThis.bjørnTransformEntryHTML(document, metadata)`:**
+  Receives a document and a metadata object for each generated HTML
+  entry.
+
+- **`globalThis.bjørnTransformFeedAtom(document, metadata)`:** Receives
+  a document and a metadata object for each generated Atom feed index.
+
+- **`globalThis.bjørnTransformFeedHTML(document, metadata)`:** Receives
+  a document and a metadata object for each generated HTML feed index.
+
+- **`globalThis.bjørnTransformHead(headElement, metadata, type)`:**
+  Receives a `<head>` element, a metadata object, and a type value of
+  either `"entry"` or `"feed"`.
+
+- **`globalThis.bjørnTransformMetadata(metadata, type)`:** Receives a
+  metadata object, and a type value of either `"entry"` or `"feed"`.
+  Use this to provide any initial transformations to the metadata prior
+  to document generation.
+
+Naturally, when running 🧸📔 Bjørn normally from the command line, all
+of these hooks are undefined. You can write your own small build script
+to define them, and run that instead :—
+
+```js
+#!/usr/bin/env -S deno run --allow-read --allow-write
+// custom_build.js
+
+// Define your hooks first…
+globalThis.bjørnTransformHead = (headElement, metadata, type) => {
+  Array.from(headElement.children)
+    .find(($) => $.localName == "title")
+    .textContent += " | My Cool Site";
+};
+
+// Then run the script…
+await import("./build.js");
+```
  
  [CommonMark]: <https://commonmark.org>
  [Deno]: <https://deno.land/>
  
  [CommonMark]: <https://commonmark.org>
  [Deno]: <https://deno.land/>