GoHugo Asciinema

Min Hugo Version: 0.77.0

Want to insert a short demo of your tool or of a command execution on your website? You could insert a video, but then visitors can’t copy text, and it’ll make your page quite heavy. The Asciinema player solves all of that, by replaying a terminal session stored in a text file.

This Hugo module makes it very easy to use the Asciinema Player on your Hugo-powered static website.

Install

Hugo Module

Make sure the go compiler is installed as well as Hugo. To check that, run the commands below. If the programs are installed, they should not return an error. Otherwise, see the go install instructions and Hugo install instructions:
```
go version
```
```
hugo version
```
If you haven’t already, you need to initialize Hugo modules:
```
hugo mod init example.com/my-awesome-website
```
This needs to be done once per Hugo site. Read the Hugo documentation for details and background.

Install This Module

Just run:

hugo mod get -u -v cj.rs/gohugo-asciinema

Edit your Hugo config to add the module reference.

For instance, if you use a config.toml config file, add:

[module]
[[module.imports]]
path = "cj.rs/gohugo-asciinema"

For config.yml, add:

module:
imports:
    - path: cj.rs/gohugo-asciinema

Use

Use this shortcode:

{{< asciicast src="/telescope-repo-nvim/telescope.json" poster="npt:0:04" autoPlay=true loop=true >}}

Defaults

You can set default values for the player in your config.toml or params.toml etc.. For example:

`config.toml`

[params.asciinema.defaults]
theme = "solarized-dark"
loop = true
autoPlay = true
speed = 5.0

`params.toml`

[asciinema.defaults]
theme = "solarized-dark"
loop = true
autoPlay = true
speed = 5.0

Notes

src is the only required argument. All the other arguments are parameters in the object passed as the third argument of AsciinemaPlayer.create.
⚠️ src is known to sometimes cause problem with relative URLs. Your best bet is to use absolute URLs or at least from the root of the site, as in the above example.
Number and boolean should be passed without being enclosed in ", i.e. autoPlay=true, not autoPlay="true".

Advanced Features

Preloading

If you want to instruct the browser to preload the CSS and JS of the Asciinema Player, only when the page contains an asciicast, you can add the following line in the <head> tag of your template:

{{- partial "asciinema_css_js_smart_preload" . -}}

Themes often offer ways to do this easily. For instance with Hugo PaperMod, it’s in this file.

This partial will also cause some services to send Early Hints. That can further improve the page load time.

Features

Displays a message when JavaScript is disabled in the user browser
Fingerprinted assets, to improve caching and ultimately your site performance
Optional preloading of JS and CSS assets
Easy update with hugo mod get -u cj.rs/gohugo-asciinema

How Are the Sources of the Player Generated?

The Asciinema Player version is fetched from the official repository in the corresponding version. Then, if prebuilt JS/CSS files are provided they are used, so that you can verify that this module is actually distributing the original code. If not, these files are generated following the instructions from Asciinema Player Readme.

Contribute

Contributions (documentation or code improvements in particular) are welcome, see contributing!

To test your code changes locally, you can change your configuration so that your local version is loaded. Here is an example in TOML:

[module]
replacements = "cj.rs/gohugo-asciinema -> /some/path/gohugo-asciinema"
[[module.imports]]
path = "cj.rs/gohugo-asciinema"

Please consider sending a PR with your patches, it’s always appreciated and will save you the trouble of maintaining the changes on your own!

Install#

Hugo Module#

Install This Module#

Use#

Defaults#

config.toml#

params.toml#

Notes#

Advanced Features#

Preloading#

Features#

How Are the Sources of the Player Generated?#

Contribute#