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.
-
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 versionhugo version -
If you haven’t already, you need to initialize Hugo modules:
hugo mod init example.com/my-awesome-websiteThis needs to be done once per Hugo site. Read the Hugo documentation for details and background.
-
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.tomlconfig file, add:[module] [[module.imports]] path = "cj.rs/gohugo-asciinema"
For
config.yml, add:module: imports: - path: cj.rs/gohugo-asciinema
Use this shortcode:
{{< asciicast src="/telescope-repo-nvim/telescope.json" poster="npt:0:04" autoPlay=true loop=true >}}You can set default values for the player in your config.toml or params.toml etc.. For example:
[params.asciinema.defaults]
theme = "solarized-dark"
loop = true
autoPlay = true
speed = 5.0[asciinema.defaults]
theme = "solarized-dark"
loop = true
autoPlay = true
speed = 5.0srcis the only required argument. All the other arguments are parameters in the object passed as the third argument ofAsciinemaPlayer.create.⚠️ srcis 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, notautoPlay="true".
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.
- 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
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.
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!