"Notebook" helper for Hugo documentation

tips & tricks
1

What

A notebook-inspired shortcode component to help document Hugo projects.

Note that unlike “usual” notebooks, this is not interactive.

Why

I needed one, and I thought it might be useful to others as well.

How to use

Documentation is available at the repos:

Component repo: GitHub - pointyfar/hugo-notebook
Demo repo: GitHub - pointyfar/hugo-notebook-example
Demo site: https://elated-ardinghelli-b1f122.netlify.app/

How it works

Example md:

---
title: "Two"
foo:
    - bar
    - baz
lorem: ipsum
---

{{< notebook-helper/notebook >}}

{{ range $i, $e := .Params.foo }}
{{ $i }}: {{ $e }}
<br>
{{ end }}

<!-- This here is a HTML comment. -->
<!-- This won't be visible on the rendered tab. -->

{{ if isset .Params "lorem" }}
Lorem is set to {{.Params.lorem}}.
{{ end }}

{{< /notebook-helper/notebook >}}

I take the {{ .Inner }} as a string resource, then execute as template. Then produce three tabs:

  1. The .Inner, fed into the highlight function (screenshot 1)
    Screenshot

  2. The resulting resource, inside <pre><code> tags (screenshot 2)
    Screenshot

  3. The resulting resource, as is (screenshot 3)
    Screenshot

Comments / Questions / Feedback welcome!

2 Likes