Tutorial (Haunt Reference Manual)

The goal of this tutorial is to quickly create a barebones blog with +Haunt in order to demonstrate the basic workflow and key concepts. +

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. +

(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. +

3 Tutorial