The goal of this tutorial is to quickly create a barebones blog with Haunt in order to demonstrate the basic workflow and key concepts.
First, create a directory for the new site:
mkdir haunt-tutorial cd haunt-tutorial
Next, create the site configuration file haunt.scm. This is where all of the code for building the website will go.
Here’s what a simple Haunt configuration looks like:
(use-modules (haunt asset) (haunt site) (haunt builder blog) (haunt builder atom) (haunt reader skribe)) (site #:title "My First Haunt Site" #:domain "example.com" #:default-metadata '((author . "Eva Luator") (email . "firstname.lastname@example.org")) #:readers (list skribe-reader) #:builders (list (blog) (atom-feed) (atom-feeds-by-tag)))
Haunt represents the full configuration of the website using the
site procedure. Site objects specify things like the site
title, the default metadata to use for posts, which markup formats are
supported, and which builders are used to generate web pages.
With the above code saved into the haunt.scm file, the next step is to create a posts directory and populate it with articles to publish. Put the text below into a file named posts/hello.skr:
(post :title "Hello, World!" :date (make-date* 2015 10 15) :tags '("hello") (h1 [Hello, World!]) (p [This is my very first Skribe document!]))
This is a Skribe document. Skribe is one of the built-in languages that Haunt knows how to work with. It’s basically Scheme, but with support for writing literal text without quoting it all by enclosing it in square brackets. The code above defines a post named “Hello, World!” with a publishing date of 2015-10-15, whose contents are just a single heading and a paragraph.
To build the site, run
haunt build to compile all of the
HTML pages. To view the results, run
haunt serve and visit
http://localhost:8080 in a web browser.
is a handy utility that serves the contents of the website using
Guile’s built-in HTTP server. Since the blog builder was specified in
haunt.scm, the default index page is a simple listing of all
posts, which for now is a single post. Clicking on the post title
will display a page with only that post’s contents.
In addition to the basic blog builder, the haunt.scm file
specifies two additional builders for Atom feeds. The
atom-feed builder creates a feed of all posts located at
builder creates one feed for each unique tag specified in the post
metadata. There’s only one tag right now, “hello”, and its feed is
located at http://localhost/feeds/tags/hello.xml.
Tweaking a post, rebuilding the site, and viewing the results in a web
browser is the typical Haunt workflow. However, having to run
haunt build every after each edit is tedious. To address
haunt serve --watch. The Haunt web server, in
addition to serving web pages, will now watch for changes to important
files and automatically rebuild the site when they are edited. This
streamlines the workflow into an edit, save, view loop.
Now that we’ve introduced the basic utilities and concepts, continue reading this manual to learn more about Haunt’s command-line and programming interfaces.