Reusable code snippets in Hugo

I don’t like code redundancy, so I wanted to create convention for sharing snippets between language versions of the posts (because code is always in English 😉). As it turned out, it’s not that obvious in Hugo.

Research on this matter

It would seem that the matter is very simple: we create a directory, refer to the snippets from each language version, display the same in each one, and after making any changes in one place, we see the effect in each. Well, not really 😉

I’ve tried many approaches, from headless bundles, through leaf bundles, to shortcodes with .Site.GetPage usage (as I found in several articles). There always were problems, and I think it’s related to chosen translation by content directory convention.

When I was starting to think about changing convention and throwing everything into one content directory (and using *.<lang>.md for multi-language support), I stumbled upon one Hugo’s built-in function: readFile. Finally it was possible to refer files from the outside of contentDir.

Snippet implementation

I went with such file structure:

hugo/
├─ content/
│  ├─ _snippets/
│  │  ├─ 2022/
│  │  │  ├─ 04/
│  │  │  │  ├─ some-post/
│  │  │  │  │  ├─ snippet1.md
│  │  │  │  │  ├─ snippet2.md
│  ├─ en/
│  │  ├─ 2022/
│  │  │  ├─ 04/
│  │  │  │  ├─ some-post.md
│  ├─ pl/
│  │  ├─ 2022/
│  │  │  ├─ 04/
│  │  │  │  ├─ jakis-post.md

Next, I’ve created shortcode for rendering code snippets:

<!-- layouts/shortcodes/snippet.html -->

{{ $path := (printf "/content/_snippets/%s" (.Get 0))}}

{{ if eq (path.Ext $path) "" }}
    {{ $path = (printf "%s.md" $path)}}
{{ end }}

{{ if os.FileExists (path.Clean $path) }}
    {{ $page := os.ReadFile (path.Clean $path) }}

    {{ $page | markdownify }}
{{ else }}
    <div class="banner banner-danger">{{ i18n "invalid_snippet_reference" }}</div>
{{ end }}

Thanks to it, in posts I can do this:

{{</* snippet "2022/04/some-post/snippet1" */>}}

{{</* snippet "2022/04/some-post/snippet2.md" */>}}

Details worth mentioning:

Fragment of the path (content/_snippets) is hardcoded within shortcode, in order to use shorter paths in actual posts. It will allow simpler migration if there’s need for moving all snippets to different directory
*.md extension is optional: shortcode will automatically add it if omitted
just in case, path is validated with os.FileExists and if file does not exist, error banner is rendered instead. Thanks to this I can at any point easily display additional information or add error reporting (e.g. link for creating issue or JavaScript sending some request)

Important fact is that hugo server does not react to the changes in the snippets. It’s weird, since these are located in content directory, which is being watched by the server. Unfortunately, if you want to see changes in snippets, you need to run hugo server --disableFastRender AND modify file, which includes the snippet. Probably mount would fix it, but I did not try it because it complicates the config too much.

The advantage of this approach is also the fact, that in future posts I will be able to refer to the code used previously, by including a selected snippet without having to duplicate the code in another file. Are there cons? It will turn out in practice 😅

Research on this matter#

Snippet implementation#

Research on this matter

Snippet implementation