Support hooks for transforming build script output

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

index 2207d3a2e480140000aeddef0f27f67ced4659d4..6a72afb3e0e4eb075caface925e73317c5948d1a 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -113,6 +113,7 @@ file extension. A sample `.rsync-filter` might be as follows :—
  -s .gitignore
  -s /README*
  -s /build.js
+-s /deno.json
  -s index#*.xhtml
  -s #*.rdf
  ```
@@ -122,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).
  
-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/>