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 Your `entry.rdf` will look similar, but it needs a `sioc:content`
  62 property :—
  63
  64 ```xml
  65 <awol:Entry
  66   xml:lang="en"
  67   xmlns:awol="http://bblfish.net/work/atom-owl/2006-06-06/"
  68   xmlns:dc11="http://purl.org/dc/elements/1.1/"
  69   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  70   xmlns:sioc="http://rdfs.org/sioc/ns#"
  71 >
  72   <dc11:title>A Sample Post</dc11:title>
  73   <sioc:content rdf:parseType="Markdown"><![CDATA[
  74 Here is some *amazing* content!
  75
  76 I love it!
  77 ]]></sioc:content>
  78 </awol:Entry>
  79 ```
  80
  81 As you can see from the above example, 🧸📔 Bjørn supports a
  82 (nonstandard) `Markdown` value for `rdf:parseType` in addition to
  83 `Literal`. Some words of caution regarding this :—
  84
  85 1. You should always put your markdown in a `<![CDATA[` section.
  86
  87 2. Your Markdown must process into valid X·M·L (not merely H·T·M·L),
  88    due to 🧸📔 Bjørn not really understanding the latter.
  89
  90 🧸📔 Bjørn uses [rusty_markdown][rusty_markdown] for its Markdown
  91 processing, which is [CommonMark][CommonMark]‐compliant.
  92
  93 Alongside the metadata files, there are two template files,
  94 `index#feed.xhtml` (used to generate the index page) and
  95 `index#entry.xhtml` (used to generate individual blogposts). Generated
  96 content will replace the first `<bjørn-content>` element. Metadata will
  97 be inserted into the `<head>` for you automatically.
  98
  99 To modify what content is generated, simply edit `build.js` :) .
 100
 101 [CommonMark]: <https://commonmark.org>
 102 [Deno]: <https://deno.land/>
 103 [RDF11-XML]: <https://www.w3.org/TR/rdf-syntax-grammar/>
 104 [rusty_markdown]: <https://deno.land/x/rusty_markdown>