@@ -0,0 +1,202 @@
1+---
2+title: Tutorial (Part I)
3+---
4+
5+## Getting started
6+
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.
11+
12+~~~~~
13+[jasper@alice ~]$ cabal install hakyll
14+~~~~~
15+
16+## Building a simple static site
17+
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.
21+
22+~~~~~
23+[jasper@alice Sites]$ mkdir brochure
24+[jasper@alice Sites]$ cd brochure/
25+[jasper@alice brochure]$
26+~~~~~
27+
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
31+and all that).
32+
33+~~~~~
34+[jasper@alice brochure]$ ghc --make hakyll.hs
35+[1 of 1] Compiling Main ( hakyll.hs, hakyll.o )
36+Linking hakyll ...
37+[jasper@alice brochure]$ ./hakyll preview
38+Generating...
39+Starting hakyll server on port 8000...
40+~~~~~
41+
42+If you now point your browser at [localhost:8000](http://localhost:8000/) you
43+should see our simple brochure site.
44+
45+## hakyll.hs
46+
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
49+magic going on.
50+
51+~~~~~{.haskell}
52+import Text.Hakyll (hakyll)
53+main = hakyll $ do
54+ putStrLn "I'm in your computer, generating your site!"
55+~~~~~
56+
57+Note how we wrap everyting in the `hakyll` function. This is useful because
58+it will generate a very nice main function.
59+
60+## Pages
61+
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.
67+
68+~~~~~{.markdown}
69+---
70+title: About
71+---
72+Nullam imperdiet sodales orci vitae molestie.
73+Nunc quam orci, pharetra a rhoncus vitae,
74+eleifend id felis. Suspendisse potenti...
75+~~~~~
76+
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.
81+
82+## Templates
83+
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.
88+
89+~~~~~{.html}
90+<html>
91+ <head>
92+ <title>MyAweSomeCompany - $title</title>
93+ <link rel="stylesheet" type="text/css"
94+ href="css/default.css" />
95+ </head>
96+ <body>
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>
102+ </div>
103+
104+ $body
105+ </body>
106+</html>
107+~~~~~
108+
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.
115+
116+## Putting it all together
117+
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`.
121+
122+~~~~~{.haskell}
123+import Text.Hakyll (hakyll)
124+import Text.Render (renderChain)
125+import Text.Renderables (createPagePath)
126+main = hakyll $ do
127+ renderChain ["templates/default.html"]
128+ (createPagePath "about.markdown")
129+~~~~~
130+
131+Or, to render all our three pages:
132+
133+~~~~~{.haskell}
134+import Text.Hakyll (hakyll)
135+import Text.Render (renderChain)
136+import Text.Renderables (createPagePath)
137+main = hakyll $ do
138+ render "about.markdown"
139+ render "index.markdown"
140+ render "products.markdown"
141+ where render = renderChain ["templates/default.html"]
142+ . createPagePath
143+~~~~~
144+
145+This will create the following files:
146+
147+~~~~~
148+_site/about.html
149+_site/index.html
150+_site/products.html
151+~~~~~
152+
153+## CSS, images and other static files
154+
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
157+use:
158+
159+~~~~~{.haskell}
160+import Text.Hakyll (hakyll)
161+import Text.Render (static)
162+main = hakyll $ do
163+ static "css/default.css"
164+~~~~~
165+
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`.
168+
169+~~~~~{.haskell}
170+import Text.Hakyll (hakyll)
171+import Text.Render (css)
172+main = hakyll $ do
173+ css "css/default.css"
174+~~~~~
175+
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:
181+
182+~~~~~{.haskell}
183+import Text.Hakyll (hakyll)
184+import Text.Render (css)
185+import Text.File (directory)
186+main = hakyll $ do
187+ directory css "css"
188+~~~~~
189+
190+## Deploying
191+
192+To setup your site, simply copy the contents of `_site` to your hosting provider
193+using your favorite piece of software.
194+
195+## That's it!
196+
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).
200+
201+If you feel comfortable with the basics, here is a next tutorial:
202+[building a simple blog](tutorial2.html).