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 To modify what content is generated, simply edit `build.js` :) .
 127
 128 [CommonMark]: <https://commonmark.org>
 129 [Deno]: <https://deno.land/>
 130 [RDF11-XML]: <https://www.w3.org/TR/rdf-syntax-grammar/>
 131 [rusty_markdown]: <https://deno.land/x/rusty_markdown>