diff options
Diffstat (limited to 'website/manual/Tutorial.html')
| -rw-r--r-- | website/manual/Tutorial.html | 170 |
1 files changed, 170 insertions, 0 deletions
diff --git a/website/manual/Tutorial.html b/website/manual/Tutorial.html new file mode 100644 index 0000000..6068592 --- /dev/null +++ b/website/manual/Tutorial.html @@ -0,0 +1,170 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 2015 David Thompson + + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A +copy of the license is included in the section entitled "GNU Free +Documentation License". --> +<!-- Created by GNU Texinfo 6.0, http://www.gnu.org/software/texinfo/ --> +<head> +<title>Haunt Reference Manual: Tutorial</title> + +<meta name="description" content="Haunt Reference Manual: Tutorial"> +<meta name="keywords" content="Haunt Reference Manual: Tutorial"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Command_002dline-Interface.html#Command_002dline-Interface" rel="next" title="Command-line Interface"> +<link href="Building.html#Building" rel="prev" title="Building"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.indentedblock {margin-right: 0em} +blockquote.smallindentedblock {margin-right: 0em; font-size: smaller} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smalllisp {margin-left: 3.2em} +kbd {font-style: oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space: nowrap} +span.nolinebreak {white-space: nowrap} +span.roman {font-family: serif; font-weight: normal} +span.sansserif {font-family: sans-serif; font-weight: normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en"> +<a name="Tutorial"></a> +<div class="header"> +<p> +Next: <a href="Command_002dline-Interface.html#Command_002dline-Interface" accesskey="n" rel="next">Command-line Interface</a>, Previous: <a href="Installation.html#Installation" accesskey="p" rel="prev">Installation</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Tutorial-1"></a> +<h2 class="chapter">3 Tutorial</h2> + +<p>The goal of this tutorial is to quickly create a barebones blog with +Haunt in order to demonstrate the basic workflow and key concepts. +</p> +<p>First, create a directory for the new site: +</p> +<div class="example"> +<pre class="example">mkdir haunt-tutorial +cd haunt-tutorial +</pre></div> + +<p>Next, create the site configuration file <samp>haunt.scm</samp>. This is +where all of the code for building the website will go. +</p> +<p>Here’s what a simple Haunt configuration looks like: +</p> +<div class="example"> +<pre class="example">(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))) +</pre></div> + +<p>Haunt represents the full configuration of the website using the +<code>site</code> 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. +</p> +<p>With the above code saved into the <samp>haunt.scm</samp> file, the next +step is to create a <samp>posts</samp> directory and populate it with +articles to publish. Put the text below into a file named +<samp>posts/hello.skr</samp>: +</p> +<div class="example"> +<pre class="example">(post + :title "Hello, World!" + :date (make-date* 2015 10 15) + :tags '("hello") + + (h1 [Hello, World!]) + + (p [This is my very first Skribe document!])) +</pre></div> + +<p>This is a +<a href="http://www.nongnu.org/skribilo/doc/user-3.html#skribe-syntax">Skribe</a> 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. +</p> +<p>To build the site, run <code>haunt build</code> to compile all of the +HTML pages. To view the results, run <code>haunt serve</code> and visit +<a href="http://localhost:8080">http://localhost:8080</a> in a web browser. <code>haunt serve</code> +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 +<samp>haunt.scm</samp>, 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. +</p> +<p>In addition to the basic blog builder, the <samp>haunt.scm</samp> file +specifies two additional builders for Atom feeds. The +<code>atom-feed</code> builder creates a feed of all posts located at +<a href="http://localhost:8080/feed.xml">http://localhost:8080/feed.xml</a>. The <code>atom-feeds-by-tag</code> +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 <a href="http://localhost/feeds/tags/hello.xml">http://localhost/feeds/tags/hello.xml</a>. +</p> +<p>Tweaking a post, rebuilding the site, and viewing the results in a web +browser is the typical Haunt workflow. However, having to run +<code>haunt build</code> every after each edit is tedious. To address +this, run <code>haunt serve --watch</code>. 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. +</p> +<p>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. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Command_002dline-Interface.html#Command_002dline-Interface" accesskey="n" rel="next">Command-line Interface</a>, Previous: <a href="Installation.html#Installation" accesskey="p" rel="prev">Installation</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |