How to embed images in Haddock documentation

Question

How can I embed 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.

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

Answer 1

If you want to store your image locally you can:

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

    <<file:///home/user/your_image.png>>

Result:

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

<<your_image.png>>

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

Answer 2

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.

Answer 3

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