diagrams-pandoc

A Pandoc filter to express diagrams inline using the Haskell EDSL Diagrams.

'diagrams-pandoc' replaces appropriately marked code blocks in pandoc input with images. The code blocks are compiled using the Haskell EDSL Diagrams. Each block should define a Diagram named example, to be output. This name and other defaults can be overridden by command-line arguments to the diagrams-pandoc program.

A pandoc filter to express diagrams inline using the haskell EDSL diagrams.

Usage

Create an input file called demo.md with the following text:

    This is how to draw a circle:
    ~~~ diagram
    example = circle 1
    ~~~

Install diagrams-pandoc, then run pandoc as follows:

    pandoc -t html demo.md --filter diagrams-pandoc -o demo.html -s

The file demo.html should now have an img tag pointing at a PNG of a circle.

Attributes

You can specify attributes to control how the diagram is generated. The following, for example,

    ~~~ {.diagram width=800 height=400 caption="A circle"}
    example = circle 1
    ~~~

will override the default width and height of the generated diagram, and provide a caption for it. The following attributes are supported:

• width: The width of the generated diagram, in pixels. The default is 500.
• height: The height of the generated diagram, in pixels. The default is 200.
• caption: The caption of the diagram. Providing a caption makes the diagram appear as a figure, rather than an inline image. Diagrams have no caption by default.
• alt: The alt text of the diagram. The caption is used as the default value if it is provided, otherwise it is empty.

Details

diagrams-pandoc compiles code blocks containing diagrams expressions and includes the resulting images in the pandoc markup. It is meant to be run as a pandoc filter as shown above.

diagrams-pandoc evaluates the diagrams expression example by default. This can be modified by passing a command line argument.

diagrams-pandoc is aware of two code block classes. A block with the diagram class will be replaced by the resulting image---the code will not appear in the output. A block with the diagram-haskell class will produce both an image and a (syntax highlighted) code block. The input block is replaced by image appears before the code block, and the diagram-haskell class is replaced by the haskell class, so that pandoc can perform syntax highlighting as usual.

diagrams-pandoc produces images in the pdf format when used with the latex and beamer writers of pandoc and produced png output otherwise.

I have only tested with pandoc's markdown reader. In particular, the rst reader does not attach classes to code blocks, only to Div elements.

Installing

diagrams-pandoc is on Hackage. To install, run cabal install diagrams-pandoc

TODO

• use pandoc output type to pick an image file format
• for formats which are more human-readable (eg, markdown, rst), leave code block alone?
• provide command-line flags to override default behavior
• add Backends besides Cairo
• Support RST by handling Div class=diagram [CodeBlock foo bar] the same as CodeBlock class=diagram bar
• Alternate install directions using stack.