New Asciinema Hugo Module Versions

Thu, 07 Mar 2024 07:35:45 +0000

I’ve just added the last 8 versions of the Asciinema player to gohugo-asciinema, my Hugo module to easily integrate the Asciinema player to your website. Lots of exciting new features, like improved decoding and rendering efficiency as well as some support for streaming asciicasts. See the changelog links below for details of the changes. There were no changes made to the Hugo module itself, besides copying the JS & CSS from the Asciinema player.

Security note: all the releases are signed. You can even check that the files JS and CSS file in the plugin match the ones uploaded in release pages. Thanks to @ku1ik for providing these files directly!

Updating in Hugo

As usual to get the latest version the player on your website, you can run:

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

Changelogs

Here is the changelogs in the upstream Asciinema player for the updated versions:

Delay Updating the CSS and JS Files

I apologize for the delay in updating those versions in my Hugo module. I do have alerts set up when a new version comes in but I’m still testing manually to make sure that the updated version works well. This Hugo module being a side-project, I did not get the chance to do the testing any earlier. I’ve tested all those versions against various pages of my website, and it all worked well. But please feel free to report any problem you may encounter.

Moving forward, I’ll rely on a script to automate the bulk of the update, that should help updating only a few days after the release. That script is not perfect and will be improved incrementally.

Since this is a release related to Asciinema, here is an asciicast of that new script downloading the latest CSS and JS, making a commit and tagging it.

Please feel free to use this script and open a PR if you spot an update before I do in the future 😁.

GoHugo Asciinema

Sat, 21 Aug 2021 16:25:33 +0100

cljoly/gohugo-asciinema

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

Once Hugo modules are set up (see the previous section), you can install the asciinema module itself.

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="https://cj.rs/blog/cargo-info-in-neovim/demo.json" poster="npt:0:04" autoPlay=true loop=true >}}

It’s rendered like this:

To run this asciicast without javascript, use asciinema play https://cj.rs/blog/cargo-info-in-neovim/demo.json with Asciinema

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

ℹ️ Note

src is the only required argument. All the other arguments are parameters in the object passed as the third argument of AsciinemaPlayer.create.

⚠️ Warning

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.

🟣 Important

Numbers and booleans 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 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!

License

The code of this module (everything but the folder assets) is under the Apache License 2.0, like the asciinema player itself.

The assets folder contains the asciinema player. This code is Copyright Marcin Kulik, licensed under the Apache License, Version 2.0. See the upstream repository for the full sources.

Asciinema on Clément Joly – Open-Source, Rust & SQLite