]> Lady’s Gitweb - Beorn/commitdiff
Support hooks for transforming build script output 0.2.0
authorLady <redacted>
Tue, 2 May 2023 23:51:17 +0000 (16:51 -0700)
committerLady <redacted>
Tue, 2 May 2023 23:56:53 +0000 (16:56 -0700)
See README changes for a more in‐depth explanation, but the idea here
is that users should have an opportunity to make adjustments to the
build output before it is saved. This relies on defining hooks on the
global object and then using a dynamic import to get the build script
to run.

README.markdown
build.js
deno.json

index a0f30435443d0395c67ae446c3d2c4d95060fa1f..6a72afb3e0e4eb075caface925e73317c5948d1a 100644 (file)
@@ -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).
 
-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/>
index 024698acde71ebcb1fc22b8dd789320ec8cf0425..4c26518b85d4a2597126c582d50d305fd4ccd38c 100755 (executable)
--- a/build.js
+++ b/build.js
@@ -2,7 +2,7 @@
 // 🧸📔 Bjørn ∷ build.js
 // ====================================================================
 //
-// Copyright © 2022 Lady [@ Lady’s Computer].
+// Copyright © 2022‐2023 Lady [@ Lady’s Computer].
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -344,6 +344,7 @@ const applyMetadata = (node, metadata) => {
         // There is no content placeholder.
         /* do nothing */
       }
+      globalThis.bjørnTransformEntryHTML?.(document, metadata);
     } else {
       // This is not an XHTML template.
       /* do nothing */
@@ -639,6 +640,7 @@ const fillOutHead = (document, metadata, type) => {
         .href("./feed.atom")``,
     );
   }
+  globalThis.bjørnTransformHead?.(head, metadata, type);
 };
 
 /**
@@ -866,6 +868,7 @@ const metadataFromDocument = (
       /* do nothing */
     }
   }
+  globalThis.bjørnTransformMetadata?.(result, documentType);
   return validateMetadata(result, documentType);
 };
 
@@ -906,6 +909,31 @@ const validateMetadata = (metadata, type) => {
   }
 };
 
+{ // Set up global variables for use in hooks.
+  //
+  // Bjørn is principally built to be run from the command line (as a
+  // shell script) rather than conforming to typical Ecmascript module
+  // patterns. However, it recognizes hooks through various
+  // specially‐named properties on `globalThis`. After defining these
+  // hooks, a script can use a *dynamic* `import("./path/to/build.js")`
+  // to run the Bjørn build steps.
+  //
+  // To make writing scripts which make use of these hooks easier,
+  // infrastructural dependencies and useful functions are provided on
+  // `globalThis` so that wrapping scripts don’t have to attempt to
+  // manage the dependencies themselves.
+  //
+  // Note that the `Lemon/window` polyfill will already have
+  // established some D·O·M‐related global properties by the time this
+  // runs, so they don’t need to be redeclared here.
+  globalThis.Lemon = Lemon;
+  globalThis.Bjørn = {
+    addContent,
+    getLanguage,
+    setLanguage,
+  };
+}
+
 await (async () => { // this is the run script
   const writes = [];
 
@@ -1114,6 +1142,7 @@ await (async () => { // this is the run script
       /* do nothing */
     }
   }
+  globalThis.bjørnTransformFeedHTML?.(feedTemplate, feedMetadata);
   writes.push(
     Deno.writeTextFile(
       "index.xhtml",
@@ -1122,6 +1151,7 @@ await (async () => { // this is the run script
   );
 
   // Save the feed Atom file.
+  globalThis.bjørnTransformFeedAtom?.(document, feedMetadata);
   writes.push(
     Deno.writeTextFile(
       "feed.atom",
index e5f93e53683c5a3a375305fd8bfe9f495def097a..d00db959f25bb2efc82a043ed5f2477c99ae9ed4 100644 (file)
--- a/deno.json
+++ b/deno.json
@@ -1,4 +1 @@
-{
-  "fmt": { "options": { "lineWidth": 71 } },
-  "lint": { "rules": { "exclude": ["no-irregular-whitespace"] } }
-}
+{ "fmt": { "lineWidth": 71 } }
This page took 0.073811 seconds and 4 git commands to generate.