Navigation

Tutorial: FAQ

• “hGetContents: invalid argument” or “commitBuffer: invalid argument”
• “File name does not match module name” on Mac OS
• pandocCompiler/Hakyll/Pandoc eats my HTML!
• Does Hakyll support syntax highlighting?
• When should I rebuild and when should I build?

“hGetContents: invalid argument” or “commitBuffer: invalid argument”

If you get any of the errors:

commitBuffer: invalid argument (invalid character)

or:

hGetContents: invalid argument (Invalid or incomplete multibyte or wide
    character)

It means that your Hakyll executable couldn’t write to (in the former case) or read (in the latter) from an UTF-8 encoded file.

Another possible encoding error is:

Store.set: invalid argument (cannot decode byte sequence starting from 197)

On most linux distros, you can solve this by setting your LANG to use UTF-8, using something like:

LANG=nl_BE.UTF-8 ./site build

You should also add this to your .profile, or whatever config file you use.

On Windows, running chcp 65001 before running your Hakyll executable has been reported to work.

Alternatively, you can specify this in your site.hs:

import qualified GHC.IO.Encoding as E

main :: IO ()
main = do
    E.setLocaleEncoding E.utf8
    hakyll $ do
        ...

“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 your configuration is named hakyll.hs and 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.

pandocCompiler/Hakyll/Pandoc eats my HTML!

Sometimes, it can seem that HTML pages are stripped of some arbitrary tags, e.g. <div>’s. The issue here is that, when using the default pandocCompiler, your page passes through Pandoc. Pandoc unfortunately strips away this information, giving you the “wrong” HTML.

The solution is not to use pandocCompiler, but something simpler like getResourceBody. This way, your HTML is not touched.

Does Hakyll support syntax highlighting?

Syntax highlighting is enabled by default in Hakyll if you are using a somewhat recent version of Pandoc (1.9 and onwards). Note that you also need to include some CSS in order for this to work! This site, for example, uses the default Pandoc syntax CSS file.

To highlight a code block, you need to use Pandoc’s fenced code block syntax to set the block’s language. For example, here’s how you highlight Haskell code:

``` haskell
fac n = foldr (*) 1 [1..n]
```

For details, see Pandoc’s user guide on fenced code blocks and inline code.

When should I rebuild and when should I build?

If you execute a ./site build, Hakyll will build your site incrementally. However, we cannot detect if you edited site.hs. In this case, you first want to compile site.hs again, and then do a ./site rebuild.

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.

Other tutorials

Documentation inaccurate or out-of-date? Found a typo?