When writing technical documentation and similar it's useful to include figures and diagrams. Currently they need to be generated externally as static content and referenced in the markdown. It's common to generate figures and diagrams from textual representations using for example plantuml and ditaa. It would be useful if this generation step could be done by hugo itself.

Issue #796 proposes to add a short code that can execute any external program. This was deemed problematic for security reasons. Instead I propose to add support for specific useful external generators. There is already precedent for this in the hugo support for AsciiDoc, RST and pandoc.

I propose extending the goldmark integration so that specific fenced code blocks would be replaced by generated svg images.

Security considerations

Since this is a feature that needs to be enabled for the goldmark generator in the hugo config similar to unsafe HTML, a malicious theme or content creator would not be able to execute these generators without the site admin enabling them in the hugo config.

Examples

The following fenced code block would be replaced by a SVG representation of the diagram as output by the svgbob tool:

                                   .--->  F
          A       B      C  D     /
          *-------*-----*---*----*----->  E
                   \            ^ \
                    v          /   '--->  G
                     B --> C -'

The following fenced code block would be replaced by a SVG representation of the plot as generated by gnuplot:

set key right nobox
set samples 100
plot [-pi/2:pi] cos(x),-(sin(x) > sin(x+1) ? sin(x) : sin(x+1))

Integration options

Simplest solution is to launch the external tool and grab it's output from stdout. An option that might be viable for picchr is to use https://github.com/elliotchance/c2go to translate the single C file to Go and bundle with hugo. For svgbob it might be possible to use https://github.com/wasmerio/wasmer-go to run svgbob compiled to webassembly.

List of useful image generators

• blockdiag
• ditaa
• gnuplot
• graphviz
• picchr
• plantuml
• svgbob