Creating debug reports with Hugo inline shortcodes

Recently I discovered that Hugo added support for inline shortcodes like 30 versions ago.

According to bep, the reason I had never heard about them was simple:

You didn't ask ... (we added that to get the @getbootstrap site on Hugo, they had lots of inline scripting) ...

— Bjørn Erik Pedersen (@bepsays) June 25, 2021

A shortcode refresher

To give an idea of what this means, here’s a reminder on how you were required to use shortcodes in the past:

<!-- layouts/shortcodes/notice.html -->
<div class="notice">
  <h3>{{ .Get "title" }}</h3>
  {{ .Inner }}
</div>

<!-- content/blog/example-post.md -->
# This is an example post
{{ notice title="This is a notice" }}
This is the content inside of a notice shortcode
{{ /notice }}

^{Minor caveat with shortcode syntax1}

As you can see, the shortcode internals live in your layouts folder, and have access to your page context as well as all of the various Hugo functions. Your post is only able to pass parameters into the shortcode itself.

Now to be clear, there’s absolutely nothing wrong with doing this. In principle, it’s a good idea for your content to not have any awareness of how it’s being rendered. If you were to change the internals of the notice shortcode once, all of the pages it appears in are instantly updated upon the next render.

In saying that, the introduction of inline shortcodes allows us to do some fun things:

<!-- content/blog/example-post.md -->
# This is an example post
Check out some of these funny gags I wrote:
{{ readfile.inline }}
<ul>
  {{ range $.Site.Data.gags }}
  <li>{{ . }}</li>
  {{ end }}
</ul>
{{ /readfile.inline }}

^{Minor caveat with shortcode syntax1}

Don’t believe me? Here’s that same inline shortcode embedded in this very post:

If any of these look familiar, I just used an inline shortcode to read from the same file that powers the footer.

I haven’t used inline shortcodes to their full potential yet but I’d like to use it to add a bit more flavour to posts in future where having a dedicated shortcode would be a bit overkill.

They’ll always have their place of course! Pick the right tool for the job and all that.

Anyway, that brings me to the actual topic at hand: debug reports.

Let Hugo debug itself for you

There are always some unknowns to any site like “Do any links throw a 404?” or “Are there posts without a description?” and to shed some light on the current situation, we can get a bit meta.

It’s easiest if you just check out the debug section of my site for yourself but the short version is that I’ve been using inline shortcodes to write one off custom reports, that effectively answer these questions through introspection. That’s just a fancy way of saying I write Hugo content (reports) that show the status of other Hugo content.

There isn’t anything super complex at the moment but I used it to clean up posts where the folder names didn’t match slugs as an example.

They automatically update every time the site rebuilds so while I could keep a spreadsheet, this is a nice way of keeping that useful information close to where the action happens.

I made a list of various reports that I’ll consider generating going forward and some will be a bit more tricky than others.

In all likelihood, the most interesting ones will just be reading from data sources generated by external scripts running either locally or via a CI pipeline. It’s nicer to see all this information on one place even if I could just read the logs from my terminal or a pipeline run.

Ah, and before I forget, the actual source for the reports is visible on Github so feel free to borrow anything you’d like to use for your own site. They’re pretty naively written but they get the job done.

Hopefully I’ve given you something to consider and if you think of any interesting report types that aren’t on my list, I’d love to hear about them!