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).

score 10 · Accepted Answer · edited Dec 30 '12 at 23:23

10

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:

Enter image description here

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.

edited Dec 30 '12 at 23:23

Peter Mortensen

30,738
21
105
131

answered Dec 26 '12 at 16:52

0xAX

20,957
26
117
206

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 ```<>``` 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 `<>` – 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
(At least for the documentation in the package directory) – amindfv Dec 29 '12 at 01:44

score 10 · Answer 2 · answered Dec 26 '12 at 18:57

10

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.

answered Dec 26 '12 at 18:57

Brent Yorgey

2,043
16
17

2

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
1

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
4

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

score 9 · Answer 3 · answered May 10 '14 at 13:43

9

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

answered May 10 '14 at 13:43

phadej

11,947
41
78

How to embed images in Haddock documentation

3 Answers3