From f2905021ec094ee794017586581c175ee98e7bb2 Mon Sep 17 00:00:00 2001 From: Jasper Van der Jeugt Date: Sun, 13 Jan 2013 12:36:45 +0100 Subject: Add a clay tutorial --- web/site.hs | 6 +- .../a-guide-to-the-hakyll-module-zoo.markdown | 99 ++++++++++++++++++++++ web/tutorials/guide.markdown | 99 ---------------------- web/tutorials/using-clay-with-hakyll.markdown | 38 +++++++++ 4 files changed, 142 insertions(+), 100 deletions(-) create mode 100644 web/tutorials/a-guide-to-the-hakyll-module-zoo.markdown delete mode 100644 web/tutorials/guide.markdown create mode 100644 web/tutorials/using-clay-with-hakyll.markdown (limited to 'web') diff --git a/web/site.hs b/web/site.hs index 2fca8e0..0f99af2 100644 --- a/web/site.hs +++ b/web/site.hs @@ -3,6 +3,7 @@ import Control.Applicative ((<$>)) import Control.Arrow (second) import Control.Monad (forM_) +import Data.Char (isDigit) import Data.List (isPrefixOf, partition) import Data.Monoid (mappend) import Hakyll @@ -111,4 +112,7 @@ hackage url -------------------------------------------------------------------------------- -- | Partition tutorials into tutorial series & other articles partitionTutorials :: [Item a] -> ([Item a], [Item a]) -partitionTutorials = partition $ matches (fromRegex "\\d*-.*") . itemIdentifier +partitionTutorials = partition $ \i -> + case splitPath (toFilePath $ itemIdentifier i) of + [_, (x : _)] -> isDigit x + _ -> False diff --git a/web/tutorials/a-guide-to-the-hakyll-module-zoo.markdown b/web/tutorials/a-guide-to-the-hakyll-module-zoo.markdown new file mode 100644 index 0000000..8376952 --- /dev/null +++ b/web/tutorials/a-guide-to-the-hakyll-module-zoo.markdown @@ -0,0 +1,99 @@ +--- +title: A Guide to the Hakyll Module Zoo +author: Brent Yorgey +--- + +The hakyll package [contains a bewildering array](/reference/) of modules, and +it's hard to know where to look when you are just getting started -- especially +since many of them are mostly just used by Hakyll internally and not that useful +to website authors. This guide provides a quick reference to the contents of the +most important and useful modules. + +## Core modules + +These are the modules containing the fundamental tools and concepts +you need to get started building a site with hakyll. + +* [Hakyll.Core.Compiler](/reference/Hakyll-Core-Compiler.html) + + This is one of the modules you should look at first. It defines the + fundamental `Compiler` type and primitive `Compiler`s as well as several + variants on `load`, which allow you to bring together multiple resources to + create a single output. + +* [Hakyll.Core.Routes](/reference/Hakyll-Core-Routes.html) + + Specify where compiled items should go in the output site. + +* [Hakyll.Core.Rules](/reference/Hakyll-Core-Rules.html) + + Specify which compilers and routes should be used on which resources. Also + has combinators for versions (necessary if you want to use the same + resources for multiple purposes). + +* [Hakyll.Core.Identifier.Pattern](/reference/Hakyll-Core-Identifier-Pattern.html) + + Combinators for creating *patterns*, i.e. predicates that pick out a set of + resources: filesystem globs, explicit lists, regular expressions, and so on. + +* [Hakyll.Web.Page](/reference/Hakyll-Web-Pandoc.html) + + Provides functions for rendering your pages using pandoc, with a varying + degree of high-levelness. + +* [Hakyll.Web.Template](/reference/Hakyll-Web-Template.html) + + Templates specify how to take the content of an item and turn it into HTML + output. + +* [Hakyll.Web.Template.Context](/reference/Hakyll-Web-Template-Context.html) + + You can't do much with a `Template` if you don't have a `Context`: this + module provides some predefined `Context`s and the tools to build your own. + +* [Hakyll.Main](/reference/Hakyll-Main.html) + + The main `hakyll` function that runs the whole show. There is also a + `hakyllWith` function which allows for a custom configuration. + +## Pre-packaged solutions + +These modules contain some "pre-packaged" solutions for common situations. They +can be used as-is, or their source can be used as inspiration for your own +tools. + +* [Hakyll.Web.Page.List](/reference/Hakyll-Web-Page-List.html) + + Combine several pages into a list, such as a list of posts, images in a + gallery, etc. + +* [Hakyll.Web.Feed](/reference/Hakyll-Web-Feed.html) + + Create RSS feeds. + +* [Hakyll.Web.Tags](/reference/Hakyll-Web-Tags.html) + + Work with tags and categories. + +## Useful utilities + +* [Hakyll.Core.UnixFilter](/reference/Hakyll-Core-UnixFilter.html) + + Use any unix utility as a compiler. + +* [Hakyll.Core.Util.File](/reference/Hakyll-Core-Util-File.html) + + Utility functions for working with the file system. + +* [Hakyll.Core.Util.String](/reference/Hakyll-Core-Util-String.html) + + A few utility functions for working with `String`s (trim spaces, find and + replace, split on regexp). + +## Advanced customization + +* [Hakyll.Core.Writable](/reference/Hakyll-Core-Writable.html) + + The `Writable` class is for resources which can be written to disk as part + of the output site. You can specify how to write your own custom types to + disk by giving them a `Writable` instance. diff --git a/web/tutorials/guide.markdown b/web/tutorials/guide.markdown deleted file mode 100644 index 8376952..0000000 --- a/web/tutorials/guide.markdown +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: A Guide to the Hakyll Module Zoo -author: Brent Yorgey ---- - -The hakyll package [contains a bewildering array](/reference/) of modules, and -it's hard to know where to look when you are just getting started -- especially -since many of them are mostly just used by Hakyll internally and not that useful -to website authors. This guide provides a quick reference to the contents of the -most important and useful modules. - -## Core modules - -These are the modules containing the fundamental tools and concepts -you need to get started building a site with hakyll. - -* [Hakyll.Core.Compiler](/reference/Hakyll-Core-Compiler.html) - - This is one of the modules you should look at first. It defines the - fundamental `Compiler` type and primitive `Compiler`s as well as several - variants on `load`, which allow you to bring together multiple resources to - create a single output. - -* [Hakyll.Core.Routes](/reference/Hakyll-Core-Routes.html) - - Specify where compiled items should go in the output site. - -* [Hakyll.Core.Rules](/reference/Hakyll-Core-Rules.html) - - Specify which compilers and routes should be used on which resources. Also - has combinators for versions (necessary if you want to use the same - resources for multiple purposes). - -* [Hakyll.Core.Identifier.Pattern](/reference/Hakyll-Core-Identifier-Pattern.html) - - Combinators for creating *patterns*, i.e. predicates that pick out a set of - resources: filesystem globs, explicit lists, regular expressions, and so on. - -* [Hakyll.Web.Page](/reference/Hakyll-Web-Pandoc.html) - - Provides functions for rendering your pages using pandoc, with a varying - degree of high-levelness. - -* [Hakyll.Web.Template](/reference/Hakyll-Web-Template.html) - - Templates specify how to take the content of an item and turn it into HTML - output. - -* [Hakyll.Web.Template.Context](/reference/Hakyll-Web-Template-Context.html) - - You can't do much with a `Template` if you don't have a `Context`: this - module provides some predefined `Context`s and the tools to build your own. - -* [Hakyll.Main](/reference/Hakyll-Main.html) - - The main `hakyll` function that runs the whole show. There is also a - `hakyllWith` function which allows for a custom configuration. - -## Pre-packaged solutions - -These modules contain some "pre-packaged" solutions for common situations. They -can be used as-is, or their source can be used as inspiration for your own -tools. - -* [Hakyll.Web.Page.List](/reference/Hakyll-Web-Page-List.html) - - Combine several pages into a list, such as a list of posts, images in a - gallery, etc. - -* [Hakyll.Web.Feed](/reference/Hakyll-Web-Feed.html) - - Create RSS feeds. - -* [Hakyll.Web.Tags](/reference/Hakyll-Web-Tags.html) - - Work with tags and categories. - -## Useful utilities - -* [Hakyll.Core.UnixFilter](/reference/Hakyll-Core-UnixFilter.html) - - Use any unix utility as a compiler. - -* [Hakyll.Core.Util.File](/reference/Hakyll-Core-Util-File.html) - - Utility functions for working with the file system. - -* [Hakyll.Core.Util.String](/reference/Hakyll-Core-Util-String.html) - - A few utility functions for working with `String`s (trim spaces, find and - replace, split on regexp). - -## Advanced customization - -* [Hakyll.Core.Writable](/reference/Hakyll-Core-Writable.html) - - The `Writable` class is for resources which can be written to disk as part - of the output site. You can specify how to write your own custom types to - disk by giving them a `Writable` instance. diff --git a/web/tutorials/using-clay-with-hakyll.markdown b/web/tutorials/using-clay-with-hakyll.markdown new file mode 100644 index 0000000..e557c3d --- /dev/null +++ b/web/tutorials/using-clay-with-hakyll.markdown @@ -0,0 +1,38 @@ +--- +title: Using Clay with Hakyll +author: Jasper Van der Jeugt +--- + +[Clay](http://sebastiaanvisser.github.com/clay/) is a nice CSS preprocesser +written in Haskell. There are multiple options to use this together with Hakyll, +but in this short tutorial I focus on what I think is the best way. + +This method requires every Clay file to have a `main` function which just prints +the CSS. This would be an example of such a file: + +``` haskell +{-# LANGUAGE OverloadedStrings #-} +import Clay +import qualified Data.Text.Lazy.IO as T + +test :: Css +test = ... + +main :: IO () +main = T.putStr $ render test +``` + +Let's assume such a file is called `css/foo.hs`. In our compiled site, we want +to map this to `css/foo.css`. Hence, the route is a simple `setExtension`. For +compilation, we simply pass the Clay file through `runghc` with no options. + +```haskell +match "css/*.hs" $ do + route $ setExtension "css" + compile $ getResourceString >>= withItemBody (unixFilter "runghc" []) +``` + +The major advantage of using this method (as opposed to importing the Clay files +in `site.hs`) is that now Hakyll will only recompile the Clay files when +necessary, and you don't have to manually recompile your `site.hs` each time you +want to tweak your CSS a little. -- cgit v1.2.3