1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
|
#+TITLE: Building a Site with Haunt
#+TAGS: Programming, Lisp, Web, Emacs, Org
#+DATE: <2023-06-27 Tue>
Hello! This is my first post on this website, which I've created over the last several days with the static site generator [[https:dthompson.us/projects/haunt][Haunt]]. It's my first time really delving into Web tech; I think for pedagogical purposes it was a really effective choice: I know Scheme already from reading SICP and my use of Guix, and Haunt is sufficiently minimal, low-level, and little-used that I learn a good bit of HTML syntax and have to style things with CSS. Conversely, it does enough that it'll be really easy to maintain once up-and-running with it, much moreso than writing bare HTML.
* An Overview of Haunt
Haunt, fundamentally, views websites as programs (according to the manual). The actual facts on the ground are a little rockier: the documentation hasn't been updated in a /long/ time, and there are undocumented releases on the git repository with extensive, new convenience featues. The fundamental object is the =site=: a record containing all of the top-level information about the website. Among this information is a list of "builder" procedures which synthesize individual pages of the website from input, Scheme code, and external files. The outputs of these builders are "page" objects (something which the command line tells me is deprecated in favor of "serialized-artifacts," which aren't documented anywhere), which are copied into the output directory. There are also "readers," which take as input "posts," blog posts written in a sensible markup format, and output pages representing the posts, alongside corresponding modifications to the site to present a correct aggregation of those posts. Useful, and only in the latest v0.3.0 release, is the =publisher= argument, which takes a description of how to copy all output pages to a remote. The only method currently is rsync, but that's all that's much better than nothing.
The CLI is bare: =haunt build= to produce output pages, =haunt serve= to pop the output on localhost:8080 (with =--watch= to refresh on file changes), and =haunt publish= to run the publisher on what's been =haunt build='ed most recently.
Styling is manual, with CSS, unless you would like to build CSS inline style propagation logic into SHTML and rewrite all the Haunt default logic to use it (good idea!). If you decide to also use Haunt, be sure to
* Practical Advice
Look to the source code of existing sites. Some examples:
- [[https://dthompson.us][dthompson.us]]
- [[https://bendersteed.tech][bendersteed.tech]]
- [[https://jakob.space][jakob.space]]
- This one (see footer).
Generally, what's needed is:
- Make an =assets= directory with CSS, fonts, top-level images, etc.
- Define a =theme= (creates header and footers for posts, alongside some other stuff)
- Define some static pages
- Integrate your chosen post format, and point Haunt at the place the posts live
I highly recommend the [[https://git.sr.ht/~jakob/ox-haunt][ox-haunt]] package, if you already use Emacs and Org. It provides some minor tweaks to =org-export-html= so as to integrate seamlessly with Haunt; that's how I've written this. As I don't know too much about Org, and generally just use it as a markup language, I had to stumble into the following information:
- Metadata goes at the top of the file, e.g. =#+TITLE: Building a Site with Haunt=
- The correct format to be interpreted as Haunt post tags is: =#+TAGS: Programming, Lisp, Web, Emacs, Org=
- The =#+DATE: <2023-06-27 Tue>= can be populated automatically with =C-c .= / =org-time-stamp=.
- putting =# -*- after-save-hook: (ox-haunt-export-to-html); -*-= at the very top of the file (note: zero-width space to satisfy Org-mode; beware copying) will automatically update the HTML files on saving the Org-mode post.
- Putting posts in their own directory makes managing post-specific images easier.
* What I'm Doing With This Site
Succinctly, writing about anything and everything which takes my fancy. Some of it may not be for you; I will likely write a fair bit about libertarian politics and Christianity. But that should be orthogonal to the rest of it. Take what you like, and leave the rest.
|
