@@ -0,0 +1,202 @@
2+title: Tutorial (Part I)
7+First, make sure you have Hakyll installed. The recommended way to do this is
8+through [hackage](http://hackage.haskell.org/) using
9+[cabal-install](http://www.haskell.org/haskellwiki/Cabal-Install). This
10+tutorial also assumes you have a basic knowledge of Haskell.
13+[jasper@alice ~]$ cabal install hakyll
16+## Building a simple static site
18+As an example to get started with, we're going to develop a so called
19+"Brochure Site" for an imaginary company. The first step is to create
20+a directory for our new site.
23+[jasper@alice Sites]$ mkdir brochure
24+[jasper@alice Sites]$ cd brochure/
25+[jasper@alice brochure]$
28+I have a [zip file](examples/brochure.zip) with the files we need for this
29+tutorial available. Please unzip it in the brochure directory we just created.
30+We'll first have a look at what we're going to create (because we're curious
34+[jasper@alice brochure]$ ghc --make hakyll.hs
35+[1 of 1] Compiling Main ( hakyll.hs, hakyll.o )
37+[jasper@alice brochure]$ ./hakyll preview
39+Starting hakyll server on port 8000...
42+If you now point your browser at [localhost:8000](http://localhost:8000/) you
43+should see our simple brochure site.
47+The main configuration file of a Hakyll site is traditionally called
48+`hakyll.hs`. It is nothing special, just a small Haskell program. There is no
52+import Text.Hakyll (hakyll)
54+ putStrLn "I'm in your computer, generating your site!"
57+Note how we wrap everyting in the `hakyll` function. This is useful because
58+it will generate a very nice main function.
62+An important concept in Hakyll is Pages. Pages are text files that can be
63+written in markdown, html or TeX. Furthermore, they can also contain some
64+metadata. The metadata is placed in the file header and surrouded by `---`
65+lines. Each line should contain a `key: value` pair. Let's have a look at the
66+`about.markdown` page.
72+Nullam imperdiet sodales orci vitae molestie.
73+Nunc quam orci, pharetra a rhoncus vitae,
74+eleifend id felis. Suspendisse potenti...
77+This contains one `key: value` pair, namely `title: About`. The rest of the
78+file is treated as markdown by pandoc. If you want to know more about
79+markdown, I think [this](http://daringfireball.net/projects/markdown/syntax)
80+is a pretty good page.
84+Another concept are the so-called templates. Templates are text files (usually
85+html files) containing a number of keys. The syntax for these keys is
86+`$identifier`. Our example site contains one template, namely
87+`templates/default.html`. Let's have a better look at that.
92+ <title>MyAweSomeCompany - $title</title>
93+ <link rel="stylesheet" type="text/css"
94+ href="css/default.css" />
97+ <h1>MyAweSomeCompany - $title</h1>
98+ <div id="navigation">
99+ <a href="index.html">Home</a>
100+ <a href="about.html">About</a>
101+ <a href="products.html">Products</a>
109+We can see how our `Page` would fit in. When we render the page we saw using
110+this template, `$title` would be replaced by `About`, and `$body` would be
111+replaced by the body of the about page. `body` is the traditional name for the
112+body of any page - that is the convention in Hakyll. Also note that in this
113+case, `$body` would be replaced by a chunk of html - the result of the
114+markdown-to-html conversion.
116+## Putting it all together
118+Now, we'll render the page using the `renderChain` function. This function
119+takes a list of templates and a renderable object. In our case, we only have
120+one template, and our renderable object is simply a `PagePath`.
123+import Text.Hakyll (hakyll)
124+import Text.Render (renderChain)
125+import Text.Renderables (createPagePath)
127+ renderChain ["templates/default.html"]
128+ (createPagePath "about.markdown")
131+Or, to render all our three pages:
134+import Text.Hakyll (hakyll)
135+import Text.Render (renderChain)
136+import Text.Renderables (createPagePath)
138+ render "about.markdown"
139+ render "index.markdown"
140+ render "products.markdown"
141+ where render = renderChain ["templates/default.html"]
145+This will create the following files:
153+## CSS, images and other static files
155+Now, we also have a css file we would like to have in the `_site` directory.
156+Static files can be rendered using the `static` function in Hakyll. We could
160+import Text.Hakyll (hakyll)
161+import Text.Render (static)
163+ static "css/default.css"
166+This would work, but let's not forget that Hakyll also has css compression. If
167+we want to use that, we would use `css` instead of `static`.
170+import Text.Hakyll (hakyll)
171+import Text.Render (css)
173+ css "css/default.css"
176+If we were to create another css file, we would have to add a line to our
177+`hakyll.hs` configuration file. This is pretty stupid, because the whole
178+directory `css` contains only css files. That's why Hakyll has a `directory`
179+function, which will execute a given function on an entire directory. So,
180+our example would become:
183+import Text.Hakyll (hakyll)
184+import Text.Render (css)
185+import Text.File (directory)
192+To setup your site, simply copy the contents of `_site` to your hosting provider
193+using your favorite piece of software.
197+Now you should fully understand our brochure site example. If you still have
198+questions, feel free to ask them on the
199+[google discussion group](http://groups.google.com/group/hakyll).
201+If you feel comfortable with the basics, here is a next tutorial:
202+[building a simple blog](tutorial2.html).