diff options
| -rw-r--r-- | web/about.markdown | 8 | ||||
| -rw-r--r-- | web/css/default.css | 26 | ||||
| -rw-r--r-- | web/examples.markdown | 4 | ||||
| -rw-r--r-- | web/hakyll.hs | 22 | ||||
| -rw-r--r-- | web/index.markdown | 16 | ||||
| -rw-r--r-- | web/philosophy.markdown | 8 | ||||
| -rw-r--r-- | web/reference.markdown | 2 | ||||
| -rw-r--r-- | web/sidebar.markdown | 4 | ||||
| -rw-r--r-- | web/templates/default.html | 2 | ||||
| -rw-r--r-- | web/templates/tutorial-item.html | 1 | ||||
| -rw-r--r-- | web/templates/tutorial.html | 16 | ||||
| -rw-r--r-- | web/templates/tutorialitem.html | 3 | ||||
| -rw-r--r-- | web/templates/tutorials.html | 4 | ||||
| -rw-r--r-- | web/tutorials/01-installation.markdown | 36 | ||||
| -rw-r--r-- | web/tutorials/02-basics.markdown (renamed from web/tutorial.markdown) | 116 | ||||
| -rw-r--r-- | web/tutorials/faq.markdown | 53 |
16 files changed, 171 insertions, 150 deletions
diff --git a/web/about.markdown b/web/about.markdown index 108663b..90d6b1c 100644 --- a/web/about.markdown +++ b/web/about.markdown @@ -2,13 +2,13 @@ title: About --- -## Code +# Code The code for Hakyll is freely available on [github](http://github.com/jaspervdj/Hakyll/). Patches and suggestions are always very welcome. -## Inspiration +# Inspiration Hakyll is not the only static site generator out there. It was inspired by the following awesome projects: @@ -17,13 +17,13 @@ following awesome projects: - [nanoc](http://nanoc.stoneship.org/) - [Jekyll](http://jekyllrb.com/) -## License +# 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 +# Authors Hakyll was originally written by [Jasper Van der Jeugt](http://jaspervdj.be), who still maintains the package. Contributors: diff --git a/web/css/default.css b/web/css/default.css index 06f664c..25509a8 100644 --- a/web/css/default.css +++ b/web/css/default.css @@ -14,19 +14,15 @@ body { div#header { height: 32px; - padding: 20px 0px 20px 60px; + margin: 20px 0px 20px 60px; + text-transform: uppercase; + font-weight: bold; + font-size: 28px; } div#header img { display: inline; - vertical-align: middle; -} - -div#header h1 { - padding-left: 10px; - display: inline; - text-transform: uppercase; - vertical-align: middle; + margin: 0px 0px 0px 0px; } div#main { @@ -65,13 +61,19 @@ a { color: black; } +h1 { + font-size: 20px; +} + h2 { - font-size: 120%; - text-transform: uppercase; + font-size: 18px; } h3 { - font-size: 100%; + font-size: 16px; +} + +h1, h2, h3 { text-transform: uppercase; } diff --git a/web/examples.markdown b/web/examples.markdown index 5e07865..f8cfbc2 100644 --- a/web/examples.markdown +++ b/web/examples.markdown @@ -2,7 +2,7 @@ title: Examples --- -## Simple examples +# Simple examples A number of simple examples are available in the GitHub repository. They can be found [here](https://github.com/jaspervdj/hakyll-examples). The README located @@ -11,7 +11,7 @@ directory using git clone git://github.com/jaspervdj/hakyll-examples.git -## People using Hakyll +# 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 diff --git a/web/hakyll.hs b/web/hakyll.hs index df92ddd..3ae9d03 100644 --- a/web/hakyll.hs +++ b/web/hakyll.hs @@ -2,6 +2,7 @@ import Hakyll import Control.Monad (forM_) import Control.Arrow ((>>>), arr) +import Data.Monoid (mempty) import Text.Pandoc main :: IO () @@ -23,15 +24,26 @@ main = hakyll $ do >>> applyTemplateCompiler "templates/default.html" >>> relativizeUrlsCompiler - -- Tutorial - match "tutorial.markdown" $ do + -- Tutorials + match "tutorials/*" $ do route $ setExtension "html" - compile $ readPageCompiler - >>> pageRenderPandocWith defaultHakyllParserState withToc + compile $ pageCompilerWith defaultHakyllParserState withToc >>> requireA "sidebar.markdown" (setFieldA "sidebar" $ arr pageBody) + >>> applyTemplateCompiler "templates/tutorial.html" >>> applyTemplateCompiler "templates/default.html" >>> relativizeUrlsCompiler + -- Tutorial list + match "tutorials.html" $ route idRoute + create "tutorials.html" $ constA mempty + >>> arr (setField "title" "Tutorials") + >>> setFieldPageList chronological + "templates/tutorial-item.html" "tutorials" "tutorials/*" + >>> requireA "sidebar.markdown" (setFieldA "sidebar" $ arr pageBody) + >>> applyTemplateCompiler "templates/tutorials.html" + >>> applyTemplateCompiler "templates/default.html" + >>> relativizeUrlsCompiler + -- Sidebar match "sidebar.markdown" $ compile pageCompiler @@ -40,7 +52,7 @@ main = hakyll $ do where withToc = defaultHakyllWriterOptions { writerTableOfContents = True - , writerTemplate = "<h2>Table of contents</h2>\n$toc$\n$body$" + , writerTemplate = "$toc$\n$body$" , writerStandalone = True } diff --git a/web/index.markdown b/web/index.markdown index ee44cf3..a65a5c5 100644 --- a/web/index.markdown +++ b/web/index.markdown @@ -2,7 +2,7 @@ title: Home --- -## Overview +# 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 @@ -12,32 +12,32 @@ configuration. Integration with [pandoc](http://johnmacfarlane.net/pandoc/) gives us markdown and TeX support, including syntax highlighting and other goodies. -## The Hakyll System +# The Hakyll System -### Write your content in whatever format you prefer +## Write your content in whatever format you prefer  -### Create compilation rules in a Haskell EDSL +## Create compilation rules in a Haskell EDSL  -### Compile it to HTML and upload it! +## Compile it to HTML and upload it!  -## Hakyll 3 +# 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 +# Getting Started You can get the latest version from hackage using `cabal install hakyll`. Then, you can: -- read the [tutorial](/tutorial.html); +- read the [tutorials](/tutorials.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 index 07a20c3..056472b 100644 --- a/web/philosophy.markdown +++ b/web/philosophy.markdown @@ -2,25 +2,25 @@ title: Philosophy --- -## Small-to-medium sites +# 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 +# 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 +# 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 +# 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, diff --git a/web/reference.markdown b/web/reference.markdown index 9b4d9e4..450f493 100644 --- a/web/reference.markdown +++ b/web/reference.markdown @@ -2,7 +2,7 @@ title: Reference --- -## Reference +# Reference We keep a copy of the reference of the latest stable version here. This reference is automatically generated by diff --git a/web/sidebar.markdown b/web/sidebar.markdown index 8396c75..24f44b7 100644 --- a/web/sidebar.markdown +++ b/web/sidebar.markdown @@ -1,9 +1,9 @@ -## Navigation +# Navigation [home](/index.html) [philosophy](/philosophy.html) [about](/about.html) -[tutorial](/tutorial.html) +[tutorials](/tutorials.html) [examples](/examples.html) [reference](/reference.html) [changelog](/changelog.html) diff --git a/web/templates/default.html b/web/templates/default.html index 040292c..78845e5 100644 --- a/web/templates/default.html +++ b/web/templates/default.html @@ -34,7 +34,7 @@ <div id="main"> <div id="header"> <img src="/images/lambda.png" alt="lambda" /> - <h1>Hakyll - $title$</h1> + Hakyll - $title$ </div> <!-- Sidebar. --> <div id="sidebar"> diff --git a/web/templates/tutorial-item.html b/web/templates/tutorial-item.html new file mode 100644 index 0000000..977fb6b --- /dev/null +++ b/web/templates/tutorial-item.html @@ -0,0 +1 @@ +<li><a href="$url$">$title$</a></li> diff --git a/web/templates/tutorial.html b/web/templates/tutorial.html index 6ce60b6..78c0b2a 100644 --- a/web/templates/tutorial.html +++ b/web/templates/tutorial.html @@ -1,10 +1,20 @@ -$body +<h1>Tutorial: $title$</h1> -<h2>Helping out</h2> +$body$ + +<h1>Other tutorials</h1> + +The other tutorials can be found <a href="/tutorials.html">here</a>. + +<h1>Helping out</h1> 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 -<a href="http://groups.google.com/group/hakyll">give some feedback</a> about +<a href="http://groups.google.com/group/hakyll">give feedback</a> about the tutorials, and especially report errors or difficulties you encountered. Thanks! + +If you run into any problems, all questions are welcome in the above google +group, or you could try the IRC channel, <code>#hakyll</code> on +<a href="http://freenode.net/">freenode</a>. diff --git a/web/templates/tutorialitem.html b/web/templates/tutorialitem.html deleted file mode 100644 index 01fb298..0000000 --- a/web/templates/tutorialitem.html +++ /dev/null @@ -1,3 +0,0 @@ -<li> - <a href="$url">$title</a> $what. -</li> diff --git a/web/templates/tutorials.html b/web/templates/tutorials.html index 6cbb4ac..36d1f03 100644 --- a/web/templates/tutorials.html +++ b/web/templates/tutorials.html @@ -1,9 +1,9 @@ -<h2>Tutorials about Hakyll</h2> +<h1>Tutorials about Hakyll</h1> <p> Here is a list of tutorials I've written about Hakyll: </p> <ul> - $body + $tutorials$ </ul> <p> All these tutorials assume you are using the latest stable version of diff --git a/web/tutorials/01-installation.markdown b/web/tutorials/01-installation.markdown new file mode 100644 index 0000000..5f763e5 --- /dev/null +++ b/web/tutorials/01-installation.markdown @@ -0,0 +1,36 @@ +--- +title: Installation +--- + +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. diff --git a/web/tutorial.markdown b/web/tutorials/02-basics.markdown index dfdf73d..bebc452 100644 --- a/web/tutorial.markdown +++ b/web/tutorials/02-basics.markdown @@ -1,42 +1,8 @@ --- -title: Tutorial +title: The basics --- -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! ------------------- +## 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 @@ -83,7 +49,7 @@ look in the directory you cloned or downloaded. [brochure-hakyll.hs]: http://github.com/jaspervdj/hakyll-examples/blob/master/brochure/hakyll.hs -### Images +## 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 @@ -122,7 +88,7 @@ content at all, we just copy the file. [copyFileCompiler]: /reference/Hakyll-Core-Writable-CopyFile.html#v:copyFileCompiler -### CSS +## CSS If we look at how the two CSS files are processed, we see something which looks very familiar: @@ -154,7 +120,7 @@ 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 +## Templates Next, we can see that the templates are compiled: @@ -168,12 +134,12 @@ good impression: ~~~~~ <html> <head> - <title>Hakyll Example - $title$</title> + <title>Hakyll Example - $$title$$</title> </head> <body> - <h1>$title$</h1> + <h1>$$title$$</h1> - $body$ + $$body$$ </body> </html> ~~~~~ @@ -181,7 +147,7 @@ good impression: 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. +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? @@ -200,7 +166,7 @@ directory! We want to use it to lay out other items -- so we need to load By using the `templates/*` pattern, we compile all templates in one go. -### Pages +## Pages The code for pages looks suspiciously more complicated: @@ -267,9 +233,9 @@ 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 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 @@ -324,59 +290,3 @@ 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`. diff --git a/web/tutorials/faq.markdown b/web/tutorials/faq.markdown new file mode 100644 index 0000000..f8a3087 --- /dev/null +++ b/web/tutorials/faq.markdown @@ -0,0 +1,53 @@ +--- +title: FAQ +--- + +## Does Hakyll support 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 should I rebuild and when should I build? + +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. + +## Problem with 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`. |