How does caching work?

[bergus]

(related to #383) I've seen you can use cached, but unfortunately it is undocumented :-( What does it do, how does it work?

• Does it prevent a compiler from running multiple times during a single build?
• Does it prevent a compiler from running at all for subsequent builds, or: does it put the results in the storeDirectory (/_cache)?
• Does it even stop items that depend on it from being recomputed when the results are the same in the previous run?

I'd love to see docs for cached or even an (advanced) tutorial article about caching in Hakyll in general (what is put in _cache etc). If some of the steps above are not implemented, would it be possible to add them?

[Vtec234]

Something that works for me (or at least seems to work, so far) is that cached can be used to store (well, cache) partial compilation results. For example, pandoc compilation takes a long time, while applying templates is almost instant. I don't want to wait for pandoc every time I change a template, so I can do this:

    compile $ cached "pandoc" pandocCompiler
      >>= loadAndApplyTemplate "templates/post.html"  postCtx
      >>= loadAndApplyTemplate "templates/default.html" postCtx
      >>= relativizeUrls

Then changing templates/post.html will reuse the cached results from pandoc and rebuild quickly.