@@ -1,6 +1,49 @@
1−-- | A page is an important concept in Hakyll: it has a body (usually of the
2−-- type 'String') and number of metadata fields. This type is used to represent
3−-- pages on your website.
1+-- | A page is a key-value mapping, representing a page on your site
2+--
3+-- A page is an important concept in Hakyll. It is a key-value mapping, and has
4+-- one field with an arbitrary type. A 'Page' thus consists of
5+--
6+-- * a key-value mapping (of the type @Map String String@);
7+--
8+-- * a value (of the type @a@).
9+--
10+-- Usually, the value will be a 'String' as well, and the value will be the body
11+-- of the page.
12+--
13+-- Pages can be constructed using Haskell, but they are usually parsed from a
14+-- file. The file format for pages is pretty straightforward.
15+--
16+-- > This is a simple page
17+-- > consisting of two lines.
18+--
19+-- This is a valid page with two lines. If we load this in Hakyll, there would
20+-- be no metadata, and the body would be the given text. Let's look at a page
21+-- with some metadata.
22+--
23+-- > ---
24+-- > title: Alice's Adventures in Wonderland
25+-- > author: Lewis Caroll
26+-- > year: 1865
27+-- > ---
28+-- >
29+-- > Chapter I
30+-- > =========
31+-- >
32+-- > Down the Rabbit-Hole
33+-- > --------------------
34+-- >
35+-- > Alice was beginning to get very tired of sitting by her sister on the bank,
36+-- > and of having nothing to do: once or twice she had peeped into the book her
37+-- > sister was reading, but it had no pictures or conversations in it, "and
38+-- > what is the use of a book," thought Alice "without pictures or
39+-- > conversation?"
40+-- >
41+-- > ...
42+--
43+-- As you can see, we construct a metadata header in Hakyll using @---@. Then,
44+-- we simply list all @key: value@ pairs, and end with @---@ again. This page
45+-- contains three metadata fields and a body. The body is given in markdown
46+-- format, which can be easily rendered to HTML by Hakyll, using pandoc.
447--
548{-# LANGUAGE DeriveDataTypeable #-}
649module Hakyll.Web.Page