]> Lady’s Gitweb - Beorn/blob - README.markdown
Support hooks for transforming build script output
[Beorn] / README.markdown
1 # 🧸📔 Bjørn
2
3 A minimal static‐site generator with an emphasis on Atom feed
4 generation.
5
6 ## Dependencies
7
8 🧸📔 Bjørn is written in Ecmascript and intended for use with
9 [Deno][Deno].
10
11 ## Usage
12
13 Assuming `deno` is installed on your computer, you can simply do :—
14
15 ```sh
16 ./build.js ❲path-to-my-blog❳
17 ```
18
19 `❲path-to-my-blog❳` is optional; if you don’t supply a path, the
20 default is `.`.
21
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❳`.
25
26 **Note that 🧸📔 Bjørn will silently overwrite existing `index.xhtml`
27 files in the blog directory!!**
28
29 ## Files and Locations
30
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).
38
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 :—
44
45 ```xml
46 <awol:Feed
47 rdf:about="https://blog.homepage.example"
48 xml:lang="en"
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#"
53 >
54 <dc11:title>My Cool Blog</dc11:title>
55 <dc11:creator>
56 <foaf:Person rdf:about="https://author.homepage.example" foaf:name="Me"/>
57 </dc11:creator>
58 </awol:Feed>
59 ```
60
61 The value of `rdf:about` on the root element needs to be the absolute
62 U·R·L for your blog.
63
64 Your `entry.rdf` will look similar, but it needs a `sioc:content`
65 property :—
66
67 ```xml
68 <awol:Entry
69 xml:lang="en"
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#"
74 >
75 <dc11:title>A Sample Post</dc11:title>
76 <sioc:content rdf:parseType="Markdown"><![CDATA[
77 Here is some *amazing* content!
78
79 I love it!
80 ]]></sioc:content>
81 </awol:Entry>
82 ```
83
84 In this case, the `rdf:about` can be automatically filled in based on
85 the path to the entry from the blog root.
86
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 :—
90
91 1. You should always put your markdown in a `<![CDATA[` section.
92
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.
95
96 🧸📔 Bjørn uses [rusty_markdown][rusty_markdown] for its Markdown
97 processing, which is [CommonMark][CommonMark]‐compliant.
98
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.
104
105 ## Serving Content
106
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 :—
109
110 ```rsync-filter
111 - /.rsync-filter
112 -s .git
113 -s .gitignore
114 -s /README*
115 -s /build.js
116 -s /deno.json
117 -s index#*.xhtml
118 -s #*.rdf
119 ```
120
121 ## Customization
122
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).
125
126 ### Hooks
127
128 🧸📔 Bjørn recognizes the following hooks (defined on the global
129 object) when it runs :—
130
131 - **`globalThis.bjørnTransformEntryHTML(document, metadata)`:**
132 Receives a document and a metadata object for each generated HTML
133 entry.
134
135 - **`globalThis.bjørnTransformFeedAtom(document, metadata)`:** Receives
136 a document and a metadata object for each generated Atom feed index.
137
138 - **`globalThis.bjørnTransformFeedHTML(document, metadata)`:** Receives
139 a document and a metadata object for each generated HTML feed index.
140
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"`.
144
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.
149
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 :—
153
154 ```js
155 #!/usr/bin/env -S deno run --allow-read --allow-write
156 // custom_build.js
157
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";
163 };
164
165 // Then run the script…
166 await import("./build.js");
167 ```
168
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>
This page took 0.056065 seconds and 5 git commands to generate.