Lady’s Gitweb - Beorn/blob - 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>