git.iko.soy/hakyll
on 2ef7fee help sign in
hakyll/web/tutorials/faq.markdown
79 lines 3.0 kB history raw
1---
2title: FAQ
3author: Jasper Van der Jeugt
4---
6## "hGetContents: invalid argument" or "commitBuffer: invalid argument"
8If you get any of the errors:
10 commitBuffer: invalid argument (invalid character)
12or:
14 hGetContents: invalid argument (Invalid or incomplete multibyte or wide
15 character)
17It means that your Hakyll executable couldn't write to (in the former case) or
18read (in the latter) from an UTF-8 encoded file.
20On most linux distros, you can solve this by setting your `LANG` to use UTF-8,
21using something like:
23 LANG=nl_BE.UTF-8 ./site build
25You should also add this to your `.profile`, or whatever config file you use.
27## "File name does not match module name" on Mac OS
29 Hakyll.hs:1:1:
30 File name does not match module name:
31 Saw: `Main'
32 Expected: `Hakyll'
34Is an error encountered on Mac OS when your configuration is named `hakyll.hs`
35and located on a case-insensitive filesystem. A workaround is to rename it to
36something that isn't the name of the module, for example, `site.hs`.
38## pandocCompiler/Hakyll/Pandoc eats my HTML!
40Sometimes, it can seem that HTML pages are stripped of some arbitrary tags, e.g.
41`<div>`'s. The issue here is that, when using the default `pandocCompiler`, your
42page passes through Pandoc. Pandoc unfortunately strips away this information,
43giving you the "wrong" HTML.
45The solution is not to use `pandocCompiler`, but something simpler like
46`getResourceBody`. This way, your HTML is not touched.
48## Does Hakyll support syntax highlighting?
50Syntax highlighting is enabled by default in Hakyll if you are using a somewhat
51recent version of Pandoc (1.9 and onwards). Note that you also need to include
52some CSS in order for this to work! This site, for example, uses the [default
53Pandoc syntax CSS file][syntax-css].
55To highlight a code block, you need to use Pandoc's fenced code block syntax to
56set the block's language. For example, here's how you highlight Haskell code:
58 ``` haskell
59 fac n = foldr (*) 1 [1..n]
60 ```
62For details, see Pandoc's user guide on [fenced code
63blocks][pandoc-code-blocks] and [inline code][pandoc-inline-code].
65[syntax-css]: https://github.com/jaspervdj/hakyll/blob/master/web/css/syntax.css
66[pandoc-code-blocks]: http://johnmacfarlane.net/pandoc/README.html#fenced-code-blocks
67[pandoc-inline-code]: http://johnmacfarlane.net/pandoc/README.html#verbatim
69## When should I rebuild and when should I build?
71If you execute a `./site build`, Hakyll will build your site incrementally.
72However, we can not detect if you edited `site.hs`. In this case, you first want
73to compile `site.hs` again, and then do a `./site rebuild`.
75After rebuilding your site, all files will look as "modified" to the filesystem.
76This means that when you upload your site, it will usually transfer all files --
77this can generate more traffic than necessary, since it is possible that some
78files were not actually modified. If you use `rsync`, you can counter this using
79the `--checksum` option.