3 Tutorial

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  . "eva@example.com"))
      #: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. haunt serve 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 http://localhost:8080/feed.xml. The atom-feeds-by-tag 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 this, run 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.