Hugo: Add support for generating figures and diagrams

[rigtorp]

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 https://github.com/gohugoio/hugo/issues/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

[rlcomte]

I have integrated mermaid into hugo using a shortcode and a mermain script include.
The basics work like a charm. Styling is a bit more work, but could be done as well.

[rigtorp]

Using mermaid requires client side java script. Which I try to avoid.

On Tue, Oct 13, 2020, 05:28 Rine le Comte [e-mail] wrote:

I have integrated mermaid https://mermaid-js.github.io/mermaid/#/into
hugo using a shortcode and a mermain script include.
The basics work like a charm. Styling is a bit more work, but could be
done as well.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
https://github.com/gohugoio/hugo/issues/7765#issuecomment-707704780, or
unsubscribe
https://github.com/notifications/unsubscribe-auth/AABLO2YV6SW6Q7WOZBQDTN3SKRBWJANCNFSM4SCEWBJQ
.

[pdugas]

When I write pages in Hugo, I really miss the ability to embed PlantUML diagrams like I can in GitLab's markdown. Would it be kosher to look into using PlantUML's public server to generate diagram images at build time and stashing them in resources/_gen? If so, and if someone familiar with the codebase could point me to a starting point, I'll go learn Go and see what I can figure out. Been coding for 30 years - how hard can it be? lol

[rigtorp]

@pdugas I propose that hugo would call the plantuml executable and retrieve the svg from stdout. No network access needed.

[pdugas]

GitLab replaces triple-backtick-plantuml blocks in Markdown like the example below with the resulting image.

```plantuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
```

Is there some other logic already in Hugo that gets called for portions of Markdown content like this that I could look at replicating? #7921 seems to suggest there isn't but that there is interest in supporting something along these lines, if I'm reading thing correctly.

[rigtorp]

If you load this extension for goldmark it will work exactly like that: https://github.com/OhYee/goldmark-plantuml