Extending Ghost with Graphviz Visualizations

Every self-respecting tech blog has syntax highlighting by now thanks to the many choices in server-side or client-side coloring libraries. However, readable syntax is only one part of a good tech blog.

Another important way of communicating your thoughts is visualizations through drawings. Of course you could draw these using a program such as Inkscape or Dia but there is a tried-and-true tool that will let you create drawings from a simple markup language without ever leaving your Ghost editor: Graphviz!

Thanks to a small hack introduced in this article, you can now add Graphviz visualizations to your (Ghost) blogs / website with minimal effort.

Demo

Here is the fsm example from the Graphviz Gallery rendered in Ghost:

  
digraph finite_state_machine {  
    rankdir=LR;
    size="8,5"
    node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;
    node [shape = circle];
    LR_0 -> LR_2 [ label = "SS(B)" ];
    LR_0 -> LR_1 [ label = "SS(S)" ];
    LR_1 -> LR_3 [ label = "S($end)" ];
    LR_2 -> LR_6 [ label = "SS(b)" ];
    LR_2 -> LR_5 [ label = "SS(a)" ];
    LR_2 -> LR_4 [ label = "S(A)" ];
    LR_5 -> LR_7 [ label = "S(b)" ];
    LR_5 -> LR_5 [ label = "S(a)" ];
    LR_6 -> LR_6 [ label = "S(b)" ];
    LR_6 -> LR_5 [ label = "S(a)" ];
    LR_7 -> LR_8 [ label = "S(b)" ];
    LR_7 -> LR_5 [ label = "S(a)" ];
    LR_8 -> LR_6 [ label = "S(b)" ];
    LR_8 -> LR_5 [ label = "S(a)" ];
}

Graphviz goes REST

Since graphviz is usually invoked from the command line, I've created a tiny graphviz microservice that provides graphviz rendering via REST that can be used from an <img> tag. You can check out the source code on Github and then deploy it using docker.

Installing Graphviz in Ghost

1) Deploy the graphviz microservice on your own docker server:

$ docker run -d -p 8000:8000 sseemayer/graphviz

You might want to set up a reverse proxy to your graphviz microservice to handle HTTPS termination and make it available on port 80/443.

At the end, your graphviz microservice should be available at e.g. http(s)://graphviz.yourserver.tld/

2) Inject a small script into your Ghost blog

In the 'Code Injection' section of your Ghost admin interface, add the following and replace the URL with the URL pointing to your Graphviz service:

<script>  
    $('pre.graphviz').each(function(i, el) {
        var content = $(el).text().trim();
        var img = $('<img>').attr('src', '//graphviz.yourserver.tld/viz.svg?dot=' + encodeURIComponent(content));
        $(el).replaceWith(img);
    });
</script>  

The above code will use jQuery selectors to search for <pre> tags with a graphviz class, extract the code inside of them and replace them with an <img> tag pointing to our Graphviz microservice.

3) You can now create graphviz in your blog posts like so:

<pre class="graphviz">  
digraph {  
  a -> b -> c
  a -> d
  b -> d
}
</pre>  

Result:

  
digraph {  
  a -> b -> c
  a -> d
  b -> d
}

Conclusion

Graphviz provides a lightweight markup language for annotating your thoughts using simple graphs. Using my graphviz microservice and a small script injected into the Ghost template, creating Graphviz drawings in your own blog posts becomes a breeze.

See also