git.iko.soy/hakyll
on master help sign in
hakyll/web/tutorials/faq.markdown
95 lines 3.3 kB history raw
1---
2title: FAQ
3author: Jasper Van der Jeugt
4type: article
5---
7## "hGetContents: invalid argument" or "commitBuffer: invalid argument"
9If you get any of the errors:
11 commitBuffer: invalid argument (invalid character)
13or:
15 hGetContents: invalid argument (Invalid or incomplete multibyte or wide
16 character)
18It means that your Hakyll executable couldn't write to (in the former case) or
19read (in the latter) from an UTF-8 encoded file.
21On most linux distros, you can solve this by setting your `LANG` to use UTF-8,
22using something like:
24 LANG=nl_BE.UTF-8 ./site build
26You should also add this to your `.profile`, or whatever config file you use.
28On Windows, running `chcp 65001` before running your Hakyll executable has been
29reported to work.
31Alternatively, you can specify this in your `site.hs`:
33```haskell
34import qualified GHC.IO.Encoding as E
36main :: IO ()
37main = do
38 E.setLocaleEncoding E.utf8
39 hakyll $ do
40 ...
41```
43## "File name does not match module name" on Mac OS
45 Hakyll.hs:1:1:
46 File name does not match module name:
47 Saw: `Main'
48 Expected: `Hakyll'
50Is an error encountered on Mac OS when your configuration is named `hakyll.hs`
51and located on a case-insensitive filesystem. A workaround is to rename it to
52something that isn't the name of the module, for example, `site.hs`.
54## pandocCompiler/Hakyll/Pandoc eats my HTML!
56Sometimes, it can seem that HTML pages are stripped of some arbitrary tags, e.g.
57`<div>`'s. The issue here is that, when using the default `pandocCompiler`, your
58page passes through Pandoc. Pandoc unfortunately strips away this information,
59giving you the "wrong" HTML.
61The solution is not to use `pandocCompiler`, but something simpler like
62`getResourceBody`. This way, your HTML is not touched.
64## Does Hakyll support syntax highlighting?
66Syntax highlighting is enabled by default in Hakyll if you are using a somewhat
67recent version of Pandoc (1.9 and onwards). Note that you also need to include
68some CSS in order for this to work! This site, for example, uses the [default
69Pandoc syntax CSS file][syntax-css].
71To highlight a code block, you need to use Pandoc's fenced code block syntax to
72set the block's language. For example, here's how you highlight Haskell code:
74 ``` haskell
75 fac n = foldr (*) 1 [1..n]
76 ```
78For details, see Pandoc's user guide on [fenced code
79blocks][pandoc-code-blocks] and [inline code][pandoc-inline-code].
81[syntax-css]: https://github.com/jaspervdj/hakyll/blob/master/web/css/syntax.css
82[pandoc-code-blocks]: http://johnmacfarlane.net/pandoc/README.html#fenced-code-blocks
83[pandoc-inline-code]: http://johnmacfarlane.net/pandoc/README.html#verbatim
85## When should I rebuild and when should I build?
87If you execute a `./site build`, Hakyll will build your site incrementally.
88However, we can not detect if you edited `site.hs`. In this case, you first want
89to compile `site.hs` again, and then do a `./site rebuild`.
91After rebuilding your site, all files will look as "modified" to the filesystem.
92This means that when you upload your site, it will usually transfer all files --
93this can generate more traffic than necessary, since it is possible that some
94files were not actually modified. If you use `rsync`, you can counter this using
95the `--checksum` option.