Freeze the context; make it available to hooks

[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 .gitignore
  -s /README*
  -s /build.js
+-s /deno.json
  -s index#*.xhtml
  -s #*.rdf
  ```
  -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).
  
  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/>