Hugo shortcodes for asciinema
Find the finished theme at https://github.com/hybras/hugo-asciinema[the repo]
https://asciinema.org[Asciinema] records and replays your terminal sessions.
It makes it easy to share shell scripts and their output, which is a boon for documenting complex workflows.
Best of all, it can be easily embedded using a https://asciinema.org/docs/embedding[script] or the https://github.com/asciinema/asciinema-player/tree/master#self-hosting-quick-start[`
I wanted create a https://gohugo.io/templates/shortcode-templates[hugo shortcode] (template for the https://gohugo.io[hugo] static site generator) that makes using and self hosting asciinema easy for hugo users.
Here are some shortcodes I already found:
. In a https://www.tonylykke.com/posts/2018/06/20/embedding-asciinema-casts-in-hugo/[blog post from Tony Lykke] (which also describes how to self host asciinema in hugo)
.. con: it expects all parameters to be named (i.e.
the shortcode is not https://gohugo.io/templates/shortcode-templates/#positional-vs-named-parameters[_flexible_])
.. con: Resets the default params
. https://github.com/laozhu/hugo-nuo/blob/master/layouts/shortcodes/asciinema.html[Shortcode] from the https://github.com/laozhu/hugo-nuo[Hugo Nuo theme]
.. pro: well documented and flexible
.. con: only supports the remote player
.. con: too flexible.
It allows all parameters to be positional, which I consider bad design when more than a 2 parameters are expected
So what do I want from my shortcode?
. 1 positional parameter XOR named parameters
. Self hosted casts
. Use asciicast defaults
. Attributes that accept urls should be marked safe (safeURL)
This is the shortcode I came up with.
It checks if named parameters are used, and if so checks for the presence of each of them and includes the corresponding attribute.
The src parameter is mandatory.
Otherwise, it checks that only 1 positional param is present and assigns it to src.
[source,html]
Note that I am defying the asciinema docs, placing the deferred script in <head>, instead of at the end of <body>.
Because I am checking if .Param "asciicast" is set, make to sure to include asciicast: true in either your front matter, or site-wide in your config.
This ensures the assets are only loaded when needed.
I included the css and js in my <head> like so:
[source,html]
{{ if .Param “asciicast” }}
{{ end }} ----If you find https://github.com/asciinema/asciinema-player/tree/master#asciinema-player-element-attributes[``
All of the parameters can and should be altered to match your site.
Here’s an example.