Update website a bit
This commit is contained in:
Jasper Van der Jeugt
parent
ea694663e1
commit
efab53729d
16 changed files with 171 additions and 150 deletions
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -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/).
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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">
|
||||
|
|
|
|||
1
web/templates/tutorial-item.html
Normal file
1
web/templates/tutorial-item.html
Normal file
|
|
@ -0,0 +1 @@
|
|||
<li><a href="$url$">$title$</a></li>
|
||||
|
|
@ -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>.
|
||||
|
|
|
|||
|
|
@ -1,3 +0,0 @@
|
|||
<li>
|
||||
<a href="$url">$title</a> $what.
|
||||
</li>
|
||||
|
|
@ -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
|
||||
|
|
|
|||
36
web/tutorials/01-installation.markdown
Normal file
36
web/tutorials/01-installation.markdown
Normal file
|
|
@ -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.
|
||||
|
|
@ -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`.
|
||||
53
web/tutorials/faq.markdown
Normal file
53
web/tutorials/faq.markdown
Normal file
|
|
@ -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`.
|
||||
Loading…
Reference in a new issue