web/tutorials/faq.markdown · hakyll

on b91c8be help sign in

hakyll/web/tutorials/faq.markdown

58 lines 2.4 kB history raw

1---

2title: FAQ

3author: Jasper Van der Jeugt

4---

6## "File name does not match module name" on Mac OS

8 Hakyll.hs:1:1:

9 File name does not match module name:

10 Saw: `Main'

11 Expected: `Hakyll'

13Is an error encountered on Mac OS when your configuration is named `hakyll.hs`

14and located on a case-insensitive filesystem. A workaround is to rename it to

15something that isn't the name of the module, for example, `site.hs`.

17## pandocCompiler/Hakyll/Pandoc eats my HTML!

19Sometimes, it can seem that HTML pages are stripped of some arbitrary tags, e.g.

20`<div>`'s. The issue here is that, when using the default `pandocCompiler`, your

21page passes through Pandoc. Pandoc unfortunately strips away this information,

22giving you the "wrong" HTML.

24The solution is not to use `pandocCompiler`, but something simpler like

25`getResourceBody`. This way, your HTML is not touched.

27## Does Hakyll support syntax highlighting?

29Syntax highlighting is enabled by default in Hakyll if you are using a somewhat

30recent version of Pandoc (1.9 and onwards). Note that you also need to include

31some CSS in order for this to work! This site, for example, uses the [default

32Pandoc syntax CSS file][syntax-css].

34To highlight a code block, you need to use Pandoc's fenced code block syntax to

35set the block's language. For example, here's how you highlight Haskell code:

37 ``` haskell

38 fac n = foldr (*) 1 [1..n]

39 ```

41For details, see Pandoc's user guide on [fenced code

42blocks][pandoc-code-blocks] and [inline code][pandoc-inline-code].

44[syntax-css]: https://github.com/jaspervdj/hakyll/blob/master/web/css/syntax.css

45[pandoc-code-blocks]: http://johnmacfarlane.net/pandoc/README.html#fenced-code-blocks

46[pandoc-inline-code]: http://johnmacfarlane.net/pandoc/README.html#verbatim

48## When should I rebuild and when should I build?

50If you execute a `./site build`, Hakyll will build your site incrementally.

51However, we can not detect if you edited `site.hs`. In this case, you first want

52to compile `site.hs` again, and then do a `./site rebuild`.

54After rebuilding your site, all files will look as "modified" to the filesystem.

55This means that when you upload your site, it will usually transfer all files --

56this can generate more traffic than necessary, since it is possible that some

57files were not actually modified. If you use `rsync`, you can counter this using

58the `--checksum` option.