Emacs, scripting and anything text oriented.

Hugo: Use goat code blocks for ASCII diagrams

Kaushal Modi

Use goat code blocks if you have ASCII diagrams with a mix of text and box drawing characters.

Table of Contents

Hugo v0.93.0 added some serious features like Code Block Render Hooks and native rendering of ASCII diagrams to SVG using a GoAT  Go ASCII Tool library.

To use this feature, you put ASCII diagrams in a code block with language set to goat .. .. That’s it!

I realized I needed to use this new GoAT rendering feature because if I had an ASCII diagram with a mix of text and box drawing characters like ┌ │ ─ ┐, the positional relationship between the text and those characters wasn’t always guaranteed to remain as I intended. The reason is that based on the user’s font setup, the box drawing characters and the regular text characters could be rendered using different fonts.

This problem is best shown with this example that I was documenting in the ox-hugo manual today.

#+begin_src text
<HUGO_BASE_DIR>/content/<HUGO_SECTION>/<concatenated values of EXPORT_HUGO_SECTION_FRAG>/
                        └─────────────────────  section path  ─────────────────────────┘
#+end_src
Code Snippet 1: Mix of text and box characters in a plain text code block

Above code block renders to:

<HUGO_BASE_DIR>/content/<HUGO_SECTION>/<concatenated values of EXPORT_HUGO_SECTION_FRAG>/
                        └─────────────────────  section path  ─────────────────────────┘

The code block rendered above might look alright on your browser based on your font setup.

  • The “section path” box drawing should start at <HUGO_SECTION>/ .. and end at .. EXPORT_HUGO_SECTION_FRAG>.

But it can also look like below with a different font setup:

To fix that, we simply change the code block language to goat  If you author your posts in Markdown, this applies to you too. Just use the Markdown fenced code block syntax: ```goat .. ```.

#+begin_src goat
<HUGO_BASE_DIR>/content/<HUGO_SECTION>/<concatenated values of EXPORT_HUGO_SECTION_FRAG>/
                        └─────────────────────  section path  ─────────────────────────┘
#+end_src
Code Snippet 2: Mix of text and box characters in a goat code block

Now we will see the below rendering on any browser because you are looking at the SVG generated from the above code block by that GoAT library.

<HUGO_BASE_DIR>/content/<HUGO_SECTION>/<concatenasteecdtivoanlupeasthofEXPORT_HUGO_SECTION_FRAG>/
Caveat
The GoAT library doesn’t render the text fonts to my liking, but it’s still better than completely messing up the positional relationship between the text and the box diagram characters.

Happy grazing! 🐐

References #


Versions used: hugo v0.96.0
This is Day 11 of #100DaysToOffload.