feat(shortcode): add shortcode for asciinema (#779)

* Add asciinema shortcode and usage examples * Add asciinema shortcode * Modify * Modify * Modify * Modify * Modify * Remove old blog post and move content to dedicated documentation * Add remote cast file support * Fix remote cast file support * Modify asciinema guide * Add asciinema controls and idleTimeLimit * fix the play button position issue and update some details * Remove forced /casts/ prefix, implement flexible file lookup
2025-08-25 21:16:35 -04:00 · 2025-08-25 15:50:53 +08:00
parent fee0481a6c
commit 524af14bd1
13 changed files with 716 additions and 0 deletions
--- a/exampleSite/content/docs/guide/shortcodes/asciinema.zh-cn.md
+++ b/exampleSite/content/docs/guide/shortcodes/asciinema.zh-cn.md
@@ -0,0 +1,121 @@
+---
+title: "Asciinema Player 组件"
+linktitle: "Asciinema Player"
+sidebar:
+  exclude: true
+---
+
+asciinema shortcode 允许你在 Hugo 站点中嵌入使用 [asciinema](https://asciinema.org/) 创建的终端录制。它提供了一个功能丰富的终端播放器，具有播放控制、速度调整和主题自定义等功能。
+
+## 基本用法
+
+asciinema shortcode 支持本地 `.cast` 文件和远程 URL。以下是使用本地文件的不同方法：
+
+### 本地文件
+
+**方法 1：Assets 目录（推荐）**
+将你的 cast 文件放在 Hugo 站点的 `assets/` 目录中：
+
+```
+your-site/
+├── assets/
+│   └── demo.cast
+└── content/
+    └── my-page.md
+```
+
+在你的 markdown 文件中：
+```markdown
+{{</* asciinema file="demo.cast" */>}}
+```
+
+**方法 2：Static 目录**
+将你的 cast 文件放在 `static/` 目录中：
+
+```
+your-site/
+├── static/
+│   └── demo.cast
+└── content/
+    └── my-page.md
+```
+
+在你的 markdown 文件中：
+```markdown
+{{</* asciinema file="demo.cast" */>}}
+```
+
+**方法 3：页面包**
+对于页面包，将 cast 文件与你的 markdown 文件放在一起：
+
+```
+your-site/
+└── content/
+    └── my-page/
+        ├── index.md
+        └── demo.cast
+```
+
+在你的 markdown 文件中：
+```markdown
+{{</* asciinema file="demo.cast" */>}}
+```
+
+{{< asciinema file="casts/demo.cast" >}}
+
+### 远程文件
+
+你也可以使用来自任何远程 URL 的 cast 文件：
+
+```markdown
+{{</* asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" */>}}
+{{</* asciinema file="https://example.com/demo.cast" */>}}
+```
+
+{{< asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" >}}
+
+### 文件查找机制
+
+shortcode 会按以下顺序自动查找你的 cast 文件：
+1. **页面包资源**（如果使用页面包）
+2. **全局 assets 目录**（`assets/`）
+3. **Static 目录**（`static/`）
+4. **远程 URL**（如果路径以 `http://` 或 `https://` 开头）
+
+如果找不到文件，Hugo 会显示有用的错误信息，告诉你应该将文件放在哪里。
+
+## 高级演示
+
+这是一个展示所有可用参数的高级示例：
+
+```markdown
+{{</* asciinema 
+  file="demo.cast"
+  theme="dracula"
+  speed="2"
+  autoplay="true"
+  loop="true"
+  markers="1.5:Installation,3.2:Configuration,5.8:Testing"
+*/>}}
+```
+
+{{< asciinema 
+  file="casts/demo.cast"
+  theme="dracula"
+  speed="2"
+  autoplay="true"
+  loop="true"
+  markers="1.5:Installation,3.2:Configuration,5.8:Testing"
+>}}
+
+## 参数
+
+| 参数 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `file` | string | - | .cast 文件路径（必需）。支持本地文件、绝对路径和远程 URL |
+| `theme` | string | `"asciinema"` | 播放器主题 |
+| `speed` | number | `1` | 播放速度倍数 |
+| `autoplay` | boolean | `false` | 自动开始播放 |
+| `loop` | boolean | `false` | 循环播放 |
+| `poster` | string | `""` | 播放开始前显示的海报（预览帧）。支持 NPT 表示法（如 "npt:1:23"） |
+| `markers` | string | `""` | 逗号分隔的时间标记。格式："时间:标签" 或仅 "时间"（如 "1.5:Installation,3.2:Configuration,5.8"） |