hugo

Hugo: Use goat code blocks for ASCII diagrams

Thu Apr 7, 2022

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

Table of Contents

References

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:

Figure 1: Disproportionate box drawing characters

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.

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 #

Hugo Documentation – Diagrams