Tutorial (Haunt Reference Manual)

From 4fcd2bc0b0e2f110aff763fc7253bedde1589d7e Mon Sep 17 00:00:00 2001 From: David Thompson Date: Sun, 24 Jun 2018 05:41:06 -0400 Subject: Fix Haunt manual. The tutorial page was missing! And there was a broken link! --- manuals/haunt/Downloading.html | 6 +- manuals/haunt/Tutorial.html | 169 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 172 insertions(+), 3 deletions(-) create mode 100644 manuals/haunt/Tutorial.html (limited to 'manuals') diff --git a/manuals/haunt/Downloading.html b/manuals/haunt/Downloading.html index 993d994..3836f9f 100644 --- a/manuals/haunt/Downloading.html +++ b/manuals/haunt/Downloading.html @@ -66,9 +66,9 @@ Next: Requirem

2.1 Downloading

Official Haunt source code release tarballs can be found on the -downloads page of -Haunt’s website, along with their associated checksums. +

Official Haunt source code release tarballs can be found under Releases +in Haunt’s website, +along with their associated checksums.

diff --git a/manuals/haunt/Tutorial.html b/manuals/haunt/Tutorial.html new file mode 100644 index 0000000..48bcb95 --- /dev/null +++ b/manuals/haunt/Tutorial.html @@ -0,0 +1,169 @@ + + + + + + +Tutorial (Haunt Reference Manual) + + + + + + + + + + + + + + + + + + + + +

+ +

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

+ + + + + + -- cgit v1.2.3