Skip to content

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

License

Notifications You must be signed in to change notification settings

diagrams/diagrams-pandoc

Repository files navigation

Build Status

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

About

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

Resources

License

Stars

Watchers

Forks

Packages

No packages published