Note
The code in this repository has been moved into the graphviz repository, which is maintained under the auspices of the Pelican-plugins organization. The present repository is archived and preserved here for historical purposes.

This plugins allows the inclusion of Graphviz images using the Markdown text markup. The code for the Graphviz figure is included as a block in the article's source and the image is embedded in HTML using the Base64 format.

Graphviz must be installed in the system, otherwise this plugin will be deactivated. In Debian-based systems, do:

sudo aptitude install graphviz

You might install this plugin directly from Github along with your website sources. At the top-level directory, do, for instance:

mkdir plugins-extra 
git clone https://github.com/rlaboiss/pelican_md_graphviz.git plugins-extra/graphviz

In pelicanconf.py, add 'plugins-extra' to PLUGIN_PATHS and 'graphviz' to PLUGINS (see the Pelican documentation for details about configuring your plugins).

In the Markdown source, the Graphviz code must be inserted an individual block (i.e. separated from the rest of the material by blank lines), like the following:

..graphviz dot
digraph G {
  graph [rankdir = LR];
  Hello -> World
}

This will insert an image in your article like this:

The block must start with ..graphviz (this is configurable, see below). The word dot in the first line indicates the program that will be run for producing the image. The available programs are dot, neato, twopi, circo, fdp, sfdp, and patchwork. (see the Graphviz documentation for details). The Graphviz code must start in the second line of the block. Notice that newlines are not allowed inside the Graphviz block.

The image is generated in HTML with an <img> element inside an HTML element (by default a <div>, but this is configurable, see below). The latter has class graphviz (this is also configurable, see below). A possible CSS styling would be:

div.graphviz  {
    margin: 10px;
}
div.graphviz img {
    display: block;
    padding: 5px;
    margin-left: auto;
    margin-right: auto;
    text-align: center;
    border-style: solid;
    border-width: 1px;
    border-color: rgb(192, 177, 177);
    -webkit-border-radius: 5px;
}

The following variables can be set in the Pelican configuration file:

• GRAPHVIZ_HTML_ELEMENT: The HTML inside which the yielding Graphviz image is inserted (defaults to 'div'; another sensible possibility would be 'span').

• GRAPHVIZ_IMAGE_CLASS: Class of the <div> element including the yielding Graphviz image (defaults to 'graphviz').

• GRAPHVIZ_BLOCK_START: Starting tag for the Graphviz block in Markdown (defaults to '..graphviz').

The format of the embedded image is SVG and there is currently no way to change it. This format was chosen over others (like PNG) for two reasons. First, the generated SRC string in Base64 seem to be shorter for SVG than for PNG. Second, the image will be available in the browser as a hi-quality vectorized format. As a caveat, notice that this choice may prevent a display in browser lacking proper SVG support.

An alternative to this plugin would be the Liquid Tags extension available at Github. However, this extension needs a patch to the liquid_tags plugin, which complicates its installation.

Make this plugin work with reStructuredText. Contributions on this are welcome.

Copyright (C) 2015, 2021 Rafael Laboissiere ([email protected])

Released under the GNU Affero Public License, version 3 or later. No warranties.