diagrams-pandoc: A Pandoc filter to express diagrams inline using the Haskell EDSL _Diagrams_

[ bsd3, library, program, text ] [ Propose Tags ]

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

[Skip to Readme]


[Last Documentation]

  • Text
    • Pandoc
      • Text.Pandoc.Diagrams


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


  • No Candidates
Versions [RSS] 0.1, 0.2, 0.3, 0.3.1,, 0.4
Change log CHANGELOG.md
Dependencies base (>=4.6 && <4.20), diagrams-builder (>=0.7 && <0.9), diagrams-cairo (>=1.3 && <1.5), diagrams-core (>=1.4 && <1.6), diagrams-lib (>=1.3 && <1.5), diagrams-pandoc, diagrams-svg (>=1.4 && <1.5), directory (>=1.2 && <1.4), filepath (>=1.3 && <1.5), hashable (>=1.2 && <1.5), linear (>=1.10 && <1.23), optparse-applicative (>=0.11 && <0.19), pandoc (>=3.0 && <3.2), pandoc-types (>=1.23 && <1.24), svg-builder (>=0.1 && <0.2), text (>=1.2 && <2.2) [details]
License BSD-3-Clause
Author Daniel Bergey
Maintainer diagrams-discuss@googlegroups.com
Category Text
Bug tracker http://github.com/diagrams/diagrams-pandoc/issues
Source repo head: git clone http://github.com/diagrams/diagrams-pandoc.git
Uploaded by BrentYorgey at 2024-02-29T18:33:02Z
Distributions NixOS:0.4
Executables diagrams-pandoc
Downloads 2587 total (14 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
All reported builds failed as of 2024-02-29 [all 2 reports]

Readme for diagrams-pandoc-0.4

[back to package description]

Build Status

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


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.


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.


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.


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


  • 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