Take the 2-minute tour ×

Does anyone have experience with embedding images within local Haddock documentation?

I see for example the lens package just uses external links to images, but I'd like to store the images locally. I'd like to find the cleanest "best practice" solution, as I've devised a couple of hacks but nothing clean.

(This question is very similar to an (unanswered) question on the mailing list).

share|improve this question
add comment

3 Answers

up vote 8 down vote accepted

If you want to store your image locally you can:

-- A longer description of the package.
description: Some haskell package description.



Enter image description here

If you don't want or can't add image by relative path, just put image name without full path:


In this case, your image must be in the project/docs directory.

share|improve this answer
I can't find any way to hack this to get a relative path, though -- so it's brittle because it assumes a directory where the documentation will be used on a user's drive. Right? –  amindfv Dec 26 '12 at 20:20
Yes, you're right. If you can't get a relative path to your images, you can also add just <<Haskell-Logo-Variation.png>> and than Haskell-Logo-Variation.png image must be in the project's doc directory. –  0xAX Dec 27 '12 at 10:26
Perfect! That's just what I was looking for. Can you add that to your answer? Note also that if your image is in e.g. docs/images/, you can reference it with <<images/some_img.jpg>> –  amindfv Dec 27 '12 at 16:50
Has anybody figured out how to hook into cabal to automatically copy the picture into the documentation directory? –  lpsmith Dec 28 '12 at 11:41
@lpsmith: If you already have your docs directory with the images in it, cabal-install should just put the documentation in with the images. –  amindfv Dec 28 '12 at 14:53
show 1 more comment

As explained in that mailing list thread you reference, one option is to use a data URL to inline images into your documentation. It makes the source itself somewhat unpleasant to read (since it is interspersed with large blobs of base64-encoded data), though using Haddock's named chunks can help, by putting all the images in named chunks at the end of the file. For a real-world example of this approach, see the Haddock documentation for the circle-packing package.

share|improve this answer
It's odd that it shouldn't let you refer to data-files in your Cabal package. o_o –  Christopher Done Dec 26 '12 at 19:15
I don't think Haddock knows anything about Cabal or even ghc-pkg, does it? –  Dag Dec 26 '12 at 19:32
The data url trick is pretty neat. That might fix the performance problems we get fetching from the wiki in lens. (We changed the links in lens.cabal file to point off to imgur, because it doesn't have cache disabling problems.) –  Edward Kmett Dec 26 '12 at 20:18
Interestingly, if you try to make an image that is too much bigger than the one from the circle-packing package, haddock dies with a stack overflow. =/ –  Edward Kmett Dec 26 '12 at 20:23
@EdwardKmett That's good to know haha –  amindfv Dec 26 '12 at 20:41
add comment

As explained in a blog post by Ian Ross you could use extra-doc-files cabal option to bundle extra files into the documentation.

share|improve this answer
add comment

Your Answer


