3 A minimal static‐site generator with an emphasis on Atom feed
8 🧸📔 Bjørn is written in Ecmascript and intended for use with
13 Assuming `deno` is installed on your computer, you can simply do :—
16 ./build.js ❲path-to-my-blog❳
19 `❲path-to-my-blog❳` is optional; if you don’t supply a path, the
22 You can (of course) also run the build script using `deno run`. Bjørn
23 requires both `--allow-read` and `--allow-write` functionality for
24 everything inside `❲path-to-my-blog❳`.
26 **Note that 🧸📔 Bjørn will silently overwrite existing `index.xhtml`
27 files in the blog directory!!**
29 ## Files and Locations
31 The **feed metadata** file (also used for generating the blog homepage)
32 should be located at `❲path-to-my-blog❳/#feed.rdf`. **Entry metadata**
33 files (used for blogposts) are any files located at
34 `❲path-to-my-blog❳/❲YYYY-MM-DD❳/❲identifier❳/#entry.rdf`. It is
35 recommended that you make `❲YYYY-MM-DD❳` the date of publication for
36 the entry. `❲identifier❳` must not contain any characters not allowed
37 in U·R·L’s (e·g spaces).
39 As the extensions of these files suggest, they are
40 [R·D·F∕X·M·L][RDF11-XML] files. These can be a little cumbersome to
41 write, but they are very easy to process and manipulate with tools, so
42 they are a forward‐thinking format. Your `feed.rdf` file should
43 probably look something like this :—
47 rdf:about="https://blog.homepage.example"
49 xmlns:awol="http://bblfish.net/work/atom-owl/2006-06-06/"
50 xmlns:dc11="http://purl.org/dc/elements/1.1/"
51 xmlns:foaf="http://xmlns.com/foaf/0.1/"
52 xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
54 <dc11:title>My Cool Blog</dc11:title>
56 <foaf:Person rdf:about="https://author.homepage.example" foaf:name="Me"/>
61 The value of `rdf:about` on the root element needs to be the absolute
64 Your `entry.rdf` will look similar, but it needs a `sioc:content`
70 xmlns:awol="http://bblfish.net/work/atom-owl/2006-06-06/"
71 xmlns:dc11="http://purl.org/dc/elements/1.1/"
72 xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
73 xmlns:sioc="http://rdfs.org/sioc/ns#"
75 <dc11:title>A Sample Post</dc11:title>
76 <sioc:content rdf:parseType="Markdown"><![CDATA[
77 Here is some *amazing* content!
84 In this case, the `rdf:about` can be automatically filled in based on
85 the path to the entry from the blog root.
87 As you can see from the above example, 🧸📔 Bjørn supports a
88 (nonstandard) `Markdown` value for `rdf:parseType` in addition to
89 `Literal`. Some words of caution regarding this :—
91 1. You should always put your markdown in a `<![CDATA[` section.
93 2. Your Markdown must process into valid X·M·L (not merely H·T·M·L),
94 due to 🧸📔 Bjørn not really understanding the latter.
96 🧸📔 Bjørn uses [rusty_markdown][rusty_markdown] for its Markdown
97 processing, which is [CommonMark][CommonMark]‐compliant.
99 Alongside the metadata files, there are two template files,
100 `index#feed.xhtml` (used to generate the index page) and
101 `index#entry.xhtml` (used to generate individual blogposts). Generated
102 content will replace the first `<bjørn-content>` element. Metadata will
103 be inserted into the `<head>` for you automatically.
107 You will need a file server which supports index files with a `.xhtml`
108 file extension. A sample `.rsync-filter` might be as follows :—
123 Feel free to add styles, additional content, and whatever else you like
124 to the template files (as well as the rest of the website).
128 🧸📔 Bjørn recognizes the following hooks (defined on the global
129 object) when it runs :—
131 - **`globalThis.bjørnTransformEntryHTML(document, metadata)`:**
132 Receives a document and a metadata object for each generated HTML
135 - **`globalThis.bjørnTransformFeedAtom(document, metadata)`:** Receives
136 a document and a metadata object for each generated Atom feed index.
138 - **`globalThis.bjørnTransformFeedHTML(document, metadata)`:** Receives
139 a document and a metadata object for each generated HTML feed index.
141 - **`globalThis.bjørnTransformHead(headElement, metadata, type)`:**
142 Receives a `<head>` element, a metadata object, and a type value of
143 either `"entry"` or `"feed"`.
145 - **`globalThis.bjørnTransformMetadata(metadata, type)`:** Receives a
146 metadata object, and a type value of either `"entry"` or `"feed"`.
147 Use this to provide any initial transformations to the metadata prior
148 to document generation.
150 Naturally, when running 🧸📔 Bjørn normally from the command line, all
151 of these hooks are undefined. You can write your own small build script
152 to define them, and run that instead :—
155 #!/usr/bin/env -S deno run --allow-read --allow-write
158 // Define your hooks first…
159 globalThis.bjørnTransformHead = (headElement, metadata, type) => {
160 Array.from(headElement.children)
161 .find(($) => $.localName == "title")
162 .textContent += " | My Cool Site";
165 // Then run the script…
166 await import("./build.js");
169 [CommonMark]: <https://commonmark.org>
170 [Deno]: <https://deno.land/>
171 [RDF11-XML]: <https://www.w3.org/TR/rdf-syntax-grammar/>
172 [rusty_markdown]: <https://deno.land/x/rusty_markdown>