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

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.

GoHugo Shorturl

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

cljoly/gohugo-shorturl

Create shorter urls to external resources for your own convenience or to your own content, to get the benefits described by Derek Sivers.

Install

If you haven’t used hugo modules before (you need the go compiler):

hugo mod init

more details in hugo docs.

Then run:

hugo mod get -u -v joly.pw/gohugo-shorturl

and edit your hugo config, for instance for config.toml

[module]
  [[module.imports]]
    path = "joly.pw/gohugo-shorturl"

Use

Imagine we want to create the short url https://my.site/a and to have it redirect to https://gohugo.io/content-management/archetypes/#directory-based-archetypes:

hugo new --kind shorturl content/a.md

and then edit content/a.md:

---
title: "A"
date: 2021-03-07T13:57:13Z
draft: true
type: "shorturl"
shortto: ""
---

Change the shortto above to https://gohugo.io/content-management/archetypes/#directory-based-archetypes and draft to false

---
title: "A"
date: 2021-03-07T13:57:13Z
draft: true
type: "shorturl"
shortto: "https://gohugo.io/content-management/archetypes/#directory-based-archetypes"
---

Then deploy my.site and open https://my.site/a, you will be redirected!

Other parameters

See https://developers.google.com/search/docs/advanced/robots/robots_meta_tag?hl=en#directives

Contribute

You may use a local version of this module in hugo like this:

[module]
replacements = "joly.pw/gohugo-shorturl -> /some/path/gohugo-shorturl"
[[module.imports]]
path = "joly.pw/gohugo-shorturl"

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!

README In Static Site (RISS)

Sat, 21 Aug 2021 08:15:54 +0100

cljoly/readme-in-static-site

This fast script allows you to insert your GitHub README in your static site and apply transformations. For instance, you can read this README on GitHub and on my website.

Why?

The GitHub README of your repo needs to efficiently describe your project to GitHub’s visitor. But featuring your project on your website allows you to (among other things):

have more control on the theme and layout,
insert scripts that GitHub would prohibit (like asciinema),
have your project’s homepage independent of your hosting platform, if you wish to change at some point.

Chances are that for small projects, the page about your project is very similar to the GitHub README. Don’t duplicate efforts, describe the differences! This has been a long-awaited feature, in one form or another.

See this blog post for more details.

Testimonials

RISS made it to the first page of HackerNews and Lobsters and got comments like:

I never really understood the idea to have a separate README and index page. Glad to see i’m not the only one :)

southerntofu

Kudos for making it reusable and not specific to a single static site generator. […]

hannu

[…] A small but good idea, I like how simple riss.awk is.

lifthrasiir

Run It (Nothing to Install)

To try it with Hugo or Zola, run the following in your static-site sources:

wget https://cj.rs/riss.awk
awk -f riss.awk /path/to/my-project/README.md > content/my-project.md

If you don’t use Hugo or Zola, no problem! It should also work with any markdown-based static-site generator. Just put the markdown file where it makes sense for that generator.

To automatically update these files in your static-site sources, see Automate with GitHub Actions below. Since RISS is based on Awk, there is nothing to install, besides copying the script itself!

Example

Add a Front Matter

Most static site generators require a “front matter” at the beginning of a markdown file to attach some metadata. But you don’t want to add this to your GitHub README! Let’s hide this on GitHub and have it in the script’s output.

In you .md file on GitHub, put:





# README In Static Site (RISS)

The output of the script will be:

---
title: "README In Static Site (RISS)"
date: 2021-08-21T10:15:54
---

and this piece of yaml will be hidden on GitHub!

Replace Asciinema Image

You can’t embed the asciinema player on GitHub for security reasons. So the asciinema documentation suggests using an image there and to link it to a webpage with the player. But on your own website, you can embed this player.

In your .md file, put:


[![Finding the repositories with “telescope” in their name, with the README in the panel on the right](https://asciinema.org/a/427156.svg)](https://asciinema.org/a/427156)

The output will contain only the asciinema player:

Note: you also need to add the JS/CSS files of the asciinema player somewhere in your theme. This Hugo module makes it easy.

See the input file (typically on GitHub) and the output of the script. You can find another real word README converted to a webpage (this gives another example of asciinema conversion using a Hugo shortcode).

With some shell scripting, you could also transform all the markdown files in your repo and put them in a subdirectory of your site, so that your project’s documentation, policy, etc… lives on your site or even on a site of its own.

Your Example!

Have you used this script to transform some markdown (or other) and insert it on your website? Open an issue if you would like a link to your use case from this README!

telescope-repo.nvim: readme, website; features an Asciinema clip.
neovide: readme, first iteration of their website, PR setting this up. They have now moved to mdbook and that’s great! RISS makes the first iteration of your website easy and you are free to move to more complete solutions when your project grows.
Hugo APT Repository: readme, website, PR setting it up.

Transformations Reference

The transformations are driven by HTML comments, so that you can have different results when comments are ignored (e.g. in your GitHub README) and after executing the script on your markdown file.

Escaping

It is important that your comment starts at the beginning of the line: spaces are used for escaping, meaning that if the comment has spaces at the beginning of the line, it is ignored.

So this is escaped

Remove

Use these two comments for text you want to have in your raw .md file, but not in the output

Spread the Word

If you find this script useful, please consider inserting the following in your readme:

This will help other people find the script. Thanks for spreading the word!

If you feel especially charitable, you could put this badge somewhere:

with for instance this code:

[![](https://img.shields.io/badge/powered%20by-riss-lightgrey)](https://cj.rs/riss)

Breaking API Changes

We follow semver and any change that change would cause real world READMEs to be converted differently requires a new major version. In particular, the following is a breaking change:

adding new keywords (like remove or insert), as they may be used in the README prior to their introduction in RISS,
changing a keywords syntax.

Benchmark

Processes 17600 lines in 10 ms

$ for i in {1..100}; do shuf README.md >>bench.md; done # Create a big md file
$ wc -l README.md
176 README.md
$ wc -l bench.md
17600 bench.md
$ hyperfine 'awk -f riss.awk README.md' 'awk -f riss.awk bench.md'

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`awk -f riss.awk README.md`	2.8 ± 0.2	2.4	3.7	1.00
`awk -f riss.awk bench.md`	9.7 ± 0.4	8.9	10.7	3.46 ± 0.30

Automate with GitHub Actions

You can automatically update the markdown file in the sources of your site with GitHub Actions. Add this workflow to, for instance, .github/workflows/readme.yml:

name: Update README files

on:
  schedule:
    - cron: '30 */2 * * *'
  push:
    branches:
    - master
  # To run this workflow manually from GitHub GUI
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Check out the repo
      uses: actions/checkout@v2
    - name: Get the latest READMEs
      run: make readme-update
    - name: Commit and push if there are changes
      run: |-
        git diff
        git config --global user.email "bot@example.com"
        git config --global user.name "bot"
        git diff --quiet || (git add -u && git commit -m "Update READMEs")
        git push

and then your Makefile may contain something like:

readme-update:
	curl https://raw.githubusercontent.com/cljoly/readme-in-static-site/main/README.md | awk -f riss.awk >content/readme-in-static-site.md

Alternatively, you might configure your repositories to trigger a website rebuild when committing on your README, for instance using GitHub actions webhooks.

Contributions are Welcome!

Feel free to open an issue to discuss something or to send a PR.

See also the Spread the Word section if you would like to make more folks aware of this script.

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

New Asciinema Hugo Module Versions

Updating in Hugo

Changelogs

Delay Updating the CSS and JS Files

GoHugo Asciinema

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

License

GoHugo Shorturl

Install

Use

Other parameters

Contribute

README In Static Site (RISS)

Why?

Testimonials

Run It (Nothing to Install)

Example

Add a Front Matter

Replace Asciinema Image

More

Your Example!

Transformations Reference

Escaping

Remove

Spread the Word

Breaking API Changes

Benchmark

Automate with GitHub Actions

Contributions are Welcome!

`config.toml`

`params.toml`