From edeef66180f24e4254b512041bee617368fa1eba Mon Sep 17 00:00:00 2001 From: Jasper Van der Jeugt Date: Mon, 13 Jun 2011 08:43:28 +0200 Subject: Remove examples from this repo --- web/about.markdown | 36 +++++ web/changelog.markdown | 137 ++++++++++++++++ web/css/default.css | 118 ++++++++++++++ web/css/syntax.css | 18 +++ web/examples.markdown | 27 ++++ web/examples/brochure.zip | Bin 0 -> 9388 bytes web/examples/feedblog.zip | Bin 0 -> 6359 bytes web/examples/morepages.zip | Bin 0 -> 4222 bytes web/examples/simpleblog.zip | Bin 0 -> 6097 bytes web/examples/tagblog.zip | Bin 0 -> 6656 bytes web/hakyll.hs | 53 ++++++ web/images/brochure-files.png | Bin 0 -> 125321 bytes web/images/hakyll-system-1.png | Bin 0 -> 34950 bytes web/images/hakyll-system-2.png | Bin 0 -> 29373 bytes web/images/hakyll-system-3.png | Bin 0 -> 28774 bytes web/images/lambda.png | Bin 0 -> 878 bytes web/index.markdown | 43 +++++ web/philosophy.markdown | 28 ++++ web/reference.markdown | 10 ++ web/sidebar.markdown | 9 ++ web/templates/default.html | 72 +++++++++ web/templates/tutorial.html | 10 ++ web/templates/tutorialitem.html | 3 + web/templates/tutorials.html | 14 ++ web/tutorial.markdown | 351 ++++++++++++++++++++++++++++++++++++++++ 25 files changed, 929 insertions(+) create mode 100644 web/about.markdown create mode 100644 web/changelog.markdown create mode 100644 web/css/default.css create mode 100644 web/css/syntax.css create mode 100644 web/examples.markdown create mode 100644 web/examples/brochure.zip create mode 100644 web/examples/feedblog.zip create mode 100644 web/examples/morepages.zip create mode 100644 web/examples/simpleblog.zip create mode 100644 web/examples/tagblog.zip create mode 100644 web/hakyll.hs create mode 100644 web/images/brochure-files.png create mode 100644 web/images/hakyll-system-1.png create mode 100644 web/images/hakyll-system-2.png create mode 100644 web/images/hakyll-system-3.png create mode 100644 web/images/lambda.png create mode 100644 web/index.markdown create mode 100644 web/philosophy.markdown create mode 100644 web/reference.markdown create mode 100644 web/sidebar.markdown create mode 100644 web/templates/default.html create mode 100644 web/templates/tutorial.html create mode 100644 web/templates/tutorialitem.html create mode 100644 web/templates/tutorials.html create mode 100644 web/tutorial.markdown (limited to 'web') diff --git a/web/about.markdown b/web/about.markdown new file mode 100644 index 0000000..108663b --- /dev/null +++ b/web/about.markdown @@ -0,0 +1,36 @@ +--- +title: About +--- + +## Code + +The code for Hakyll is freely available on +[github](http://github.com/jaspervdj/Hakyll/). Patches and suggestions are +always very welcome. + +## Inspiration + +Hakyll is not the only static site generator out there. It was inspired by the +following awesome projects: + +- [yst](http://github.com/jgm/yst) +- [nanoc](http://nanoc.stoneship.org/) +- [Jekyll](http://jekyllrb.com/) + +## License + +Hakyll is available under a BSD license. Note, however, that pandoc is +released under a GPL license. Since you'll probably use Hakyll with pandoc, +you will have to license your code under a GPL-compatible license. + +## Authors + +Hakyll was originally written by [Jasper Van der Jeugt](http://jaspervdj.be), +who still maintains the package. Contributors: + +- [seschwar](http://github.com/seschwar) +- [JD Marble](http://github.com/jdmarble) +- [sargon](http://github.com/sargon) +- [Paolo Veronelli](http://github.com/paolino) +- [Benedict Eastaugh](http://extralogical.net/) +- [Nicolas Wu](http://zenzike.com/) diff --git a/web/changelog.markdown b/web/changelog.markdown new file mode 100644 index 0000000..9c6c2cf --- /dev/null +++ b/web/changelog.markdown @@ -0,0 +1,137 @@ +--- +title: Changelog +--- + +## Hakyll 3.1.1 + +- Allow `group` in rules DSL + +## Hakyll 3.1 + +- New `match` function in rules DSL +- More expressive `Pattern`s + +## Hakyll 3 + +- Complete rewrite + +## Hakyll 2.4.1 + +- Add a number of utility functions +- Fix bug in `enableIndexUrl` mode + +## Hakyll 2.4 + +- Arrow based interface to pandoc +- Easier custom fields + +## Hakyll 2.3 + +- Ability to choose between preview modes. +- Simple static configuration available. +- Support hamlet templates. + +## Hakyll 2.2.2 + +- Cabal dependency fixes. + +## Hakyll 2.2.1 + +- Allow custom time locale for `renderDate`. +- Render RSS feeds with `CDATA` sections. + +## Hakyll 2.2 + +- Allow markup languages in templates. + +## Hakyll 2.1.1 + +- Fix issues in autocompilation/preview mode. + +## Hakyll 2.1 + +May 21, 2010 + +- Expose pandoc options to HakyllConfiguration. +- Allow dashes in pages. +- Some typo's and bugs fixed. + +## Hakyll 2.0 + +March 31, 2010 + +- Rewrite of the API to a clean, Arrow based API. +- Added built-in support for RSS and Atom. +- Added more documentation. +- Added pagination. +- Many bugfixes. + +## Hakyll 1.4 + +February 17, 2010 + +- Added an autocompilation feature. +- Support for index URL's (`enableIndexUrl`). + +## Hakyll 1.3 + +January 30, 2010 + +- Added categories in addition to tags. +- Added `createListing` and `createListingWith` function for a more high-level + way to create listings. + +## Hakyll 1.2 + +January 27, 2010 + +- `Data.Binary` is now used for serialization. +- Rewrite of the caching system. +- Specialized data structure for templates. +- Caching of pages and templates. + +## Hakyll 1.1 + +January 19, 2010 + +- Switched to a custom `Hakyll` monad stack instead of the `IO` monad. +- Page sections. +- Combining renderables. +- `renderAndConcat` can now use multiple templates. + +## Hakyll 1.0 + +January 14, 2009 + +- First stable release. +- Custom templating system. +- Added `$root` key for relative URL's. + +## Hakyll 0.4 + +January 8, 2010 + +- Added examples. +- Added `ContextManipulation` type. + +## Hakyll 0.3 + +December 28, 2009 + +- Added a general `directory` function. +- Added CSS compression. +- Added tag support. +- Added a simple HTTP server for testing purposes. + +## Hakyll 0.2 + +December 16, 2010 + +- Abstracted `Renderable` type. +- Added simple caching and dependency checking. + +## Hakyll 0.1 + +December 5, 2009 + +- Initial release. diff --git a/web/css/default.css b/web/css/default.css new file mode 100644 index 0000000..06f664c --- /dev/null +++ b/web/css/default.css @@ -0,0 +1,118 @@ +html { + padding: 0px; + margin: 0px; + background-color: white; + color: black; + font-family: sans-serif; + line-height: 160%; +} + +body { + padding: 0px 0px 60px 0px; + margin: 0px; +} + +div#header { + height: 32px; + padding: 20px 0px 20px 60px; +} + +div#header img { + display: inline; + vertical-align: middle; +} + +div#header h1 { + padding-left: 10px; + display: inline; + text-transform: uppercase; + vertical-align: middle; +} + +div#main { + margin: 0px auto 0px auto; + width: 860px; +} + +div#sidebar { + margin-right: 30px; + width: 160px; + float: left; + text-align: right; +} + +div#sidebar a { + display: block; + font-size: 110%; + text-decoration: none; + margin-bottom: 10px; + text-transform: uppercase; +} + +div#content { + width: 670px; + float: right; +} + +div#footer { + padding-top: 30px; + clear: both; + font-size: 90%; + text-align: center; +} + +a { + color: black; +} + +h2 { + font-size: 120%; + text-transform: uppercase; +} + +h3 { + font-size: 100%; + text-transform: uppercase; +} + +h1 a, h2 a, h3 a { + text-decoration: none; +} + +div.column { + width: 50%; + float: left; +} + +div.column p { + padding-right: 15px; +} + +img { + display: block; + margin: 10px auto 10px auto; + border: none; +} + +ul { + list-style-type: square; + padding-left: 1em; + margin-left: 1em; +} + +code { + background-color: rgb(250, 250, 250); + border: 1px solid rgb(200, 200, 200); + padding-left: 4px; + padding-right: 4px; +} + +pre code { + display: block; + padding: 8px; + margin-bottom: 2em; +} + +p.caption { + display: none; +} diff --git a/web/css/syntax.css b/web/css/syntax.css new file mode 100644 index 0000000..1aed859 --- /dev/null +++ b/web/css/syntax.css @@ -0,0 +1,18 @@ +/* Generated by pandoc. */ +table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode, table.sourceCode pre + { margin: 0; padding: 0; border: 0; vertical-align: baseline; border: none; } +td.lineNumbers { border-right: 1px solid #AAAAAA; text-align: right; color: #AAAAAA; padding-right: 5px; padding-left: 5px; } +td.sourceCode { padding-left: 5px; } +pre.sourceCode span.kw { color: #007020; font-weight: bold; } +pre.sourceCode span.dt { color: #902000; } +pre.sourceCode span.dv { color: #40a070; } +pre.sourceCode span.bn { color: #40a070; } +pre.sourceCode span.fl { color: #40a070; } +pre.sourceCode span.ch { color: #4070a0; } +pre.sourceCode span.st { color: #4070a0; } +pre.sourceCode span.co { color: #60a0b0; font-style: italic; } +pre.sourceCode span.ot { color: #007020; } +pre.sourceCode span.al { color: red; font-weight: bold; } +pre.sourceCode span.fu { color: #06287e; } +pre.sourceCode span.re { } +pre.sourceCode span.er { color: red; font-weight: bold; } diff --git a/web/examples.markdown b/web/examples.markdown new file mode 100644 index 0000000..453a22e --- /dev/null +++ b/web/examples.markdown @@ -0,0 +1,27 @@ +--- +title: Examples +--- + +## Simple examples + +A number of simple examples are available in the GitHub repository. They can be +found [here](https://github.com/jaspervdj/hakyll/tree/master/examples). The +README located in that directory explains which example does what. + +## People using Hakyll + +A lot of sites running Hakyll also publish the source code. This is a very +interesting resource to learn from as well. If you're using Hakyll for your +site, and the source code is available, please notify me so I can add you to +this list. This list has no particular ordering. + +- , + [source](https://github.com/jaspervdj/jaspervdj) +- , + [source](https://github.com/altercation/ethanschoonover.com) +- , + [source](https://github.com/beastaugh/extralogical.net) +- , + [source](https://bitbucket.org/paul_r/blog-de-demotera) +- , + [source](http://patch-tag.com/r/byorgey/diagrams-doc/snapshot/current/content/pretty/web/) diff --git a/web/examples/brochure.zip b/web/examples/brochure.zip new file mode 100644 index 0000000..cfbe052 Binary files /dev/null and b/web/examples/brochure.zip differ diff --git a/web/examples/feedblog.zip b/web/examples/feedblog.zip new file mode 100644 index 0000000..0adaf1e Binary files /dev/null and b/web/examples/feedblog.zip differ diff --git a/web/examples/morepages.zip b/web/examples/morepages.zip new file mode 100644 index 0000000..617e0f6 Binary files /dev/null and b/web/examples/morepages.zip differ diff --git a/web/examples/simpleblog.zip b/web/examples/simpleblog.zip new file mode 100644 index 0000000..a67f362 Binary files /dev/null and b/web/examples/simpleblog.zip differ diff --git a/web/examples/tagblog.zip b/web/examples/tagblog.zip new file mode 100644 index 0000000..d758225 Binary files /dev/null and b/web/examples/tagblog.zip differ diff --git a/web/hakyll.hs b/web/hakyll.hs new file mode 100644 index 0000000..df92ddd --- /dev/null +++ b/web/hakyll.hs @@ -0,0 +1,53 @@ +{-# LANGUAGE OverloadedStrings #-} +import Hakyll +import Control.Monad (forM_) +import Control.Arrow ((>>>), arr) +import Text.Pandoc + +main :: IO () +main = hakyll $ do + match "css/*" $ do + route idRoute + compile compressCssCompiler + + -- Static directories + forM_ ["images/*", "examples/*", "reference/**"] $ \f -> match f $ do + route idRoute + compile copyFileCompiler + + -- Pages + forM_ pages $ \p -> match p $ do + route $ setExtension "html" + compile $ pageCompiler + >>> requireA "sidebar.markdown" (setFieldA "sidebar" $ arr pageBody) + >>> applyTemplateCompiler "templates/default.html" + >>> relativizeUrlsCompiler + + -- Tutorial + match "tutorial.markdown" $ do + route $ setExtension "html" + compile $ readPageCompiler + >>> pageRenderPandocWith defaultHakyllParserState withToc + >>> requireA "sidebar.markdown" (setFieldA "sidebar" $ arr pageBody) + >>> applyTemplateCompiler "templates/default.html" + >>> relativizeUrlsCompiler + + -- Sidebar + match "sidebar.markdown" $ compile pageCompiler + + -- Templates + match "templates/*" $ compile templateCompiler + where + withToc = defaultHakyllWriterOptions + { writerTableOfContents = True + , writerTemplate = "

Table of contents

\n$toc$\n$body$" + , writerStandalone = True + } + + pages = [ "about.markdown" + , "changelog.markdown" + , "examples.markdown" + , "index.markdown" + , "philosophy.markdown" + , "reference.markdown" + ] diff --git a/web/images/brochure-files.png b/web/images/brochure-files.png new file mode 100644 index 0000000..41af36e Binary files /dev/null and b/web/images/brochure-files.png differ diff --git a/web/images/hakyll-system-1.png b/web/images/hakyll-system-1.png new file mode 100644 index 0000000..69e850c Binary files /dev/null and b/web/images/hakyll-system-1.png differ diff --git a/web/images/hakyll-system-2.png b/web/images/hakyll-system-2.png new file mode 100644 index 0000000..eb424a9 Binary files /dev/null and b/web/images/hakyll-system-2.png differ diff --git a/web/images/hakyll-system-3.png b/web/images/hakyll-system-3.png new file mode 100644 index 0000000..cdffe2d Binary files /dev/null and b/web/images/hakyll-system-3.png differ diff --git a/web/images/lambda.png b/web/images/lambda.png new file mode 100644 index 0000000..fbf34a8 Binary files /dev/null and b/web/images/lambda.png differ diff --git a/web/index.markdown b/web/index.markdown new file mode 100644 index 0000000..ee44cf3 --- /dev/null +++ b/web/index.markdown @@ -0,0 +1,43 @@ +--- +title: Home +--- + +## Overview + +Hakyll is a [Haskell](http://haskell.org) library for generating static sites, +mostly aimed at small-to-medium sites and personal blogs. It is written in a +very configurable way and uses an [xmonad](http://xmonad.org)-like DSL for +configuration. + +Integration with [pandoc](http://johnmacfarlane.net/pandoc/) gives us markdown +and TeX support, including syntax highlighting and other goodies. + +## The Hakyll System + +### Write your content in whatever format you prefer + +![Write your content](/images/hakyll-system-1.png) + +### Create compilation rules in a Haskell EDSL + +![Write your rules](/images/hakyll-system-2.png) + +### Compile it to HTML and upload it! + +![Compile it](/images/hakyll-system-3.png) + +## Hakyll 3 + +Hakyll 3 has been released, and it can be installed by running +`cabal install hakyll`. For a limited time (but as long as is necessary) you can +access the old site and documentation [here](/hakyll2). + +## Getting Started + +You can get the latest version from hackage using `cabal install hakyll`. Then, +you can: + +- read the [tutorial](/tutorial.html); +- mail the [google discussion group](http://groups.google.com/group/hakyll); +- ask questions on the IRC channel: `#hakyll` on + [freenode](http://freenode.net/). diff --git a/web/philosophy.markdown b/web/philosophy.markdown new file mode 100644 index 0000000..07a20c3 --- /dev/null +++ b/web/philosophy.markdown @@ -0,0 +1,28 @@ +--- +title: Philosophy +--- + +## Small-to-medium sites + +Hakyll was written to be used for small-to-medium sites. You can do some +advanced things with it, but don't use it to build a big online shop. + +## Hakyll.hs + +It should be possible to put all configuration in one file, so data and +configuration can be strictly separated. In addition, we think this file should +never exceed a 100 lines of code. + +## High-level + +Hakyll tries to provide as many high-level functions as possible for common +tasks, while the lower-level functions should also be accessible. If you think +you're writing something that can be used for many sites, please send a patch, +or your `hakyll.hs`, and we will see what we can do. + +## Well-documented + +A key to being easy-to-use is documentation. That's why we try to provide as +many working examples as possible. If you ever create a site using hakyll, +please consider open-sourcing it, as people might be able to learn from your +code. diff --git a/web/reference.markdown b/web/reference.markdown new file mode 100644 index 0000000..9b4d9e4 --- /dev/null +++ b/web/reference.markdown @@ -0,0 +1,10 @@ +--- +title: Reference +--- + +## Reference + +We keep a copy of the reference of the latest stable version here. This +reference is automatically generated by +[Haddock](http://www.haskell.org/haddock/). You can +[find it here](reference/index.html). diff --git a/web/sidebar.markdown b/web/sidebar.markdown new file mode 100644 index 0000000..8396c75 --- /dev/null +++ b/web/sidebar.markdown @@ -0,0 +1,9 @@ +## Navigation + +[home](/index.html) +[philosophy](/philosophy.html) +[about](/about.html) +[tutorial](/tutorial.html) +[examples](/examples.html) +[reference](/reference.html) +[changelog](/changelog.html) diff --git a/web/templates/default.html b/web/templates/default.html new file mode 100644 index 0000000..040292c --- /dev/null +++ b/web/templates/default.html @@ -0,0 +1,72 @@ + + + + + + Hakyll - $title$ + + + + + + + + + + + + + +
+ + + + +
+ $body$ +
+ + +
+ + + + + + + diff --git a/web/templates/tutorial.html b/web/templates/tutorial.html new file mode 100644 index 0000000..6ce60b6 --- /dev/null +++ b/web/templates/tutorial.html @@ -0,0 +1,10 @@ +$body + +

Helping out

+ +Hakyll is an open source project, and one of the hardest parts is writing +correct, up-to-date, and understandable documentation. Therefore, the +authors would really appreciate it if you would +give some feedback about +the tutorials, and especially report errors or difficulties you encountered. +Thanks! diff --git a/web/templates/tutorialitem.html b/web/templates/tutorialitem.html new file mode 100644 index 0000000..01fb298 --- /dev/null +++ b/web/templates/tutorialitem.html @@ -0,0 +1,3 @@ +
  • + $title $what. +
    • diff --git a/web/templates/tutorials.html b/web/templates/tutorials.html new file mode 100644 index 0000000..6cbb4ac --- /dev/null +++ b/web/templates/tutorials.html @@ -0,0 +1,14 @@ +

    Tutorials about Hakyll

    +

    + Here is a list of tutorials I've written about Hakyll: +

    +
      + $body +
    +

    + All these tutorials assume you are using the latest stable version of + Hakyll. If this is not the case, you might want to update using: + 

    ghc-pkg unregister hakyll
+cabal update
+cabal install hakyll
    +

    diff --git a/web/tutorial.markdown b/web/tutorial.markdown new file mode 100644 index 0000000..920249d --- /dev/null +++ b/web/tutorial.markdown @@ -0,0 +1,351 @@ +--- +title: Tutorial +--- + +Why static websites? +-------------------- + +Modern web frameworks make it easy to create huge dynamic websites. Why would +anyone still care about a static website? + +- Static websites are fast, because it's simply files served directly from the + hard disk. +- Static websites are secure. Nobody has ever found an SQL injection in static + pages. +- Static websites are easy to deploy. Just copy them to your webhost using + (S)FTP/rsync/scp and you are done. They work on all webhosts: no CGI or extra + modules needed for the web server. + +Why Hakyll? +----------- + +Hakyll is a [Haskell] library meant for creating small-to-medium sized static +websites. It is a powerful publishing tool, precisely because of the power of +Haskell. By using the awesome [pandoc] library, it is able to create your +website from a large variety of input formats. + +[Haskell]: http://haskell.org/ +[pandoc]: http://johnmacfarlane.net/pandoc/ + +Features include: + +- easy templating system; +- a simple HTTP server for previewing and compiling your website on the go; +- powerful syntax highlighting; +- modules for common items such as tags and feeds; +- easily extensible. + +Let's get started! +------------------ + +We're going to discuss a small brochure site to start with. You can find all +code and files necessary to build this site [right here](/examples/brochure.zip) +-- feel free to look at them as we go trough the tutorial, in fact, it might be +very learnful to have a closer look at the files as we discuss them. There's a +number of files we will use: + + about.rst A simple page written in RST format + code.lhs Another page with some code (which can be highlighted) + css Directory for CSS files + |- default.css The main CSS file + \- syntax.css CSS file for code syntax highlighting + hakyll.hs Our code to generate the site + images Directory for images + \- haskell-logo.png The logo of my favorite programming language + index.markdown A simple page in markdown format + templates Directory for templates + \- default.html The main template for the site + +By default, hakyll will compile everything to the `_site` directory. We can try +this like this: + + [jasper@phoenix] ghc --make hakyll.hs + [jasper@phoenix] ./hakyll build + +Instead of using `build`, we can also use `preview`, which will fire up a +webserver serving the `_site` directory, so have a look! + +All files have been compiled, and their output has been placed in the `_site` +directory as illustrated in this diagram: + +![Brochure files](/images/brochure-files.png) + +No magic is involved at all -- we will precisely study how and why our items are +compiled like that. All of this is specified in the `hakyll.hs` file. + +### Images + +Let's start of with the `images/haskell-logo.png` file, because the processing +of this file is very simple: it is simply copied to the output directory. Let's +look at the relevant lines in the `hakyll.hs` file: + +~~~~~{.haskell} +match "images/*" $ do + route idRoute + compile copyFileCompiler +~~~~~ + +The first line specifies we will describe the process for compiling everything +in the `images/` folder: hakyll uses globs for this [^pattern]. + +[^pattern]: A little caveat is that these globs are not `String`s but + `Pattern`s, so you need the `OverloadedStrings` extension. + +We can see two simple rules next: [route] and [compile]. + +- [route] determines how the input file(s) get mapped to the output files. + [route] only deals with file names -- not with the actual content! +- [compile], on the other hand, determines how the file content is processed. + +[route]: /reference/Hakyll-Core-Rules.html#v:route +[compile]: /reference/Hakyll-Core-Rules.html#v:compile + +In this case, we select the [idRoute]: which means the file name will be kept +the same (`_site` will always be prepended automatically). This explains the +name of [idRoute]: much like the `id` function in Haskell, it also maps values +to themselves. + +[idRoute]: /reference/Hakyll-Core-Routes.html#v:idRoute + +For our compiler, we use [copyFileCompiler], meaning that we don't process the +content at all, we just copy the file. + +[copyFileCompiler]: /reference/Hakyll-Core-Writable-CopyFile.html#v:copyFileCompiler + +### CSS + +If we look at how the two CSS files are processed, we see something which looks +very familiar: + +~~~~~{.haskell} +match "css/*" $ do + route idRoute + compile compressCssCompiler +~~~~~ + +Indeed, the only difference with the images is that have now chosen for +[compressCssCompiler] -- a compiler which *does* process the content. Let's have +a quick look at the type of [compressCssCompiler]: + +[compressCssCompiler]: /reference/Hakyll-Web-CompressCss.html#v:compressCssCompiler + +~~~~~{.haskell} +compressCssCompiler :: Compiler Resource String +~~~~~ + +Intuitively, we can see this as a process which takes a `Resource` and produces +a `String`. + +- A `Resource` is simply the Hakyll representation of an item -- usually just a + file on the disk. +- The produced string is the processed CSS. + +We can wonder what Hakyll does with the resulting `String`. Well, it simply +writes this to the file specified in the `route`! As you can see, routes and +compilers work together to produce your site. + +### Templates + +Next, we can see that the templates are compiled: + +~~~~~{.haskell} +match "templates/*" $ compile templateCompiler +~~~~~ + +Let's start with the basics: what is a template? An example template gives us a +good impression: + +~~~~~ + + + Hakyll Example - $title$ + + +

    $title$

    + + $body$ + + +~~~~~ + +A template is a text file to lay our some content. The content it lays out is +called a page -- we'll see that in the next section. The syntax for templates is +intentionally very simplistic. You can bind some content by referencing the name +of the content *field* by using `$field$`, and that's it. + +You might have noticed how we specify a compiler (`compile`), but we don't set +any `route`. Why is this? + +Precisely because we don't want to our template to end up anywhere in our site +directory! We want to use it to lay out other items -- so we need to load +(compile) it, but we don't want to give it a real destination. + +By using the `templates/*` pattern, we compile all templates in one go. + +### Pages + +The code for pages looks suspiciously more complicated: + +~~~~~~{.haskell} +match (list ["about.rst", "index.markdown", "code.lhs"]) $ do + route $ setExtension "html" + compile $ pageCompiler + >>> applyTemplateCompiler "templates/default.html" + >>> relativizeUrlsCompiler +~~~~~~ + +But we'll see shortly that this actually fairly straightforward. Let's begin by +exploring what a *page* is. + +~~~~~~ +--- +title: Home +author: Jasper +--- + +So, I decided to create a site using Hakyll and... +~~~~~~ + +A page consists of two parts: a body, and metadata. As you can see above, the +syntax is not hard. The metadata part is completely optional, this is the same +page without metadata: + +~~~~~~ +So, I decided to create a site using Hakyll and... +~~~~~~ + +Hakyll supports a number of formats for the page body. Markdown, HTML and RST +are probably the most common. Hakyll will automatically guess the right format +if you use the right extension for your page. + +~~~~~~{.haskell} +match (list ["about.rst", "index.markdown", "code.lhs"]) $ do +~~~~~~ + +We see a more complicated pattern here. Some sets of files cannot be described +easily by just one pattern, and here the [list] function can help us out. In +this case, we have three specific pages we want to compile. + +[list]: /reference/Hakyll-Core-Identifier-Pattern.html#v:list + +~~~~~~{.haskell} +route $ setExtension "html" +~~~~~~ + +For our pages, we do not want to use `idRoute` -- after all, we want to generate +`.html` files, not `.markdown` files or something similar! The [setExtension] +route allows you to simply replace the extension of an item, which is what we +want here. + +[setExtension]: /reference/Hakyll-Core-Routes.html#v:setExtension + +~~~~~~{.haskell} +compile $ pageCompiler + >>> applyTemplateCompiler "templates/default.html" + >>> relativizeUrlsCompiler +~~~~~~ + +How should we process these pages? [pageCompiler] is the default compiler for +pages. [pageCompiler] does a few things: + +- It parses the page into body and metadata +- It adds some extra metadata fields such as `$url$` and `$path$` (you shouldn't + worry about these for now) +- It fill in possible `$key$`'s in it's own body +- It renders the page using pandoc + +Which basically means that we end up with a `Page` that has the HTML content we +want as body. But we don't just want the plain content on our website -- we want +to decorate it with a template, for starters. + +[pageCompiler]: /reference/Hakyll-Web-Page.html#v:pageCompiler + +Different compilers can be chained in a pipeline-like way using Arrows. Arrows +form a complicated subject, but fortunately, most Hakyll users need not be +concerned with the details. If you are interested, you can find some information +on the [Understanding arrows] page -- but the only thing you really *need* to +know is that you can chain compilers using the `>>>` operator. + +[Understanding arrows]: http://en.wikibooks.org/wiki/Haskell/Understanding_arrows + +The `>>>` operator is a lot like a flipped function composition (`flip (.)`) in +Haskell, with the important difference that `>>>` is more general and works on +all Arrows -- including Hakyll compilers. + +Here, we apply three compilers sequentially: + +1. We load and render the page using `pageCompiler` +2. We apply the template we previously loaded using [applyTemplateCompiler] +3. We relativize the URL's on the page using [relativizeUrlsCompiler] + +[applyTemplateCompiler]: /reference/Hakyll-Web-Template.html#v:applyTemplateCompiler +[relativizeUrlsCompiler]: /reference/Hakyll-Web-RelativizeUrls.html#v:relativizeUrlsCompiler + +Relativizing URL's is a very handy feature. It means that we can just use +absolute URL's everywhere in our templates and code, e.g.: + +~~~~~{.haskell} + +~~~~~ + +And Hakyll will translate this to a relative URL for each page. This means we +can host our site at `example.com` and `example.com/subdir` without changing a +single line of code. + +More tutorials are in the works... + +Various tips and tricks +----------------------- + +### Syntax highlighting + +Syntax highlighting is enabled by default in Hakyll. However, you also need to +enable it in pandoc. If no syntax highlighting shows up, try + + [jasper@phoenix] cabal install --reinstall -fhighlighting pandoc + +### When to rebuild + +If you execute a `./hakyll build`, Hakyll will build your site incrementally. +This means it will be very fast, but it will not pick up _all_ changes. + +- In case you edited `hakyll.hs`, you first want to compile it again. +- It is generally recommended to do a `./hakyll rebuild` before you deploy your + site. + +After rebuilding your site, all files will look as "modified" to the filesystem. +This means that when you upload your site, it will usually transfer all files -- +this can generate more traffic than necessary, since it is possible that some +files were not actually modified. If you use `rsync`, you can counter this using +the `--checksum` option. + +Problems +-------- + +### regex-pcre dependency on Mac OS + +Hakyll requires [regex-pcre], which might fail to build on Mac OS. To solve +this problem, make sure the [pcre] C library is installed (via homebrew or +macports). Then install [regex-pcre] using: + + cabal install --extra-include-dirs=/usr/local/include regex-pcre + +or + + cabal install --extra-include-dirs=/opt/local/include regex-pcre + +...and proceed to install Hakyll the regular way. + +[regex-pcre]: http://hackage.haskell.org/package/regex-pcre +[pcre]: http://www.pcre.org/ + +### "File name does not match module name" on Mac OS + + Hakyll.hs:1:1: + File name does not match module name: + Saw: `Main' + Expected: `Hakyll' + +Is an error encountered on Mac OS when `hakyll.hs` is located on a +case-insensitive filesystem. A workaround is to rename it to something that +isn't the name of the module, for example, `site.hs`. -- cgit v1.2.3