Asciinema Player Component

Overview

The asciinema shortcode allows you to embed terminal recordings created with asciinema in your Hugo site. It provides a rich terminal player with features like playback controls, speed adjustment, and theme customization.

Basic Usage

The asciinema shortcode supports both local .cast files and remote URLs. Here are the different ways to use local files:

Local Files

Method 1: Assets directory (recommended) Place your cast files in the assets/ directory of your Hugo site:

your-site/
├── assets/
│   └── demo.cast
└── content/
    └── my-page.md

In your markdown file:

{{< asciinema file="demo.cast" >}}

Method 2: Static directory Place your cast files in the static/ directory:

your-site/
├── static/
│   └── demo.cast
└── content/
    └── my-page.md

In your markdown file:

{{< asciinema file="demo.cast" >}}

Method 3: Page bundle For page bundles, place cast files alongside your markdown file:

your-site/
└── content/
    └── my-page/
        ├── index.md
        └── demo.cast

In your markdown file:

{{< asciinema file="demo.cast" >}}

Remote Files

You can also use cast files from any remote URL:

{{< asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" >}}
{{< asciinema file="https://example.com/demo.cast" >}}

How File Lookup Works

The shortcode automatically finds your cast files by looking in this order:

1. Page bundle resources (if using page bundles)
2. Global assets directory (assets/)
3. Static directory (static/)
4. Remote URLs (if the path starts with http:// or https://)

If a file is not found, Hugo will show a helpful error message telling you where to place the file.

Advanced Demo

Here’s a more advanced example showcasing all available parameters:

{{< asciinema 
  file="demo.cast"
  theme="dracula"
  speed="2"
  autoplay="true"
  loop="true"
  markers="1.5:Installation,3.2:Configuration,5.8:Testing"
>}}

Parameters