mirror of
https://github.com/imfing/hextra.git
synced 2025-08-25 12:56:46 -04:00
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
This commit is contained in:
Lamber
@@ -26,4 +26,5 @@ Hextra مجموعه‌ای از شورت‌کدهای زیبا را برای ب
|
||||
{{< cards >}}
|
||||
{{< card link="jupyter" title="نوت‌بوک Jupyter" icon="jupyter" tag="alpha" >}}
|
||||
{{< card link="others" title="سایر" icon="view-grid" >}}
|
||||
{{< card link="asciinema" title="Asciinema Player" icon="terminal" >}}
|
||||
{{< /cards >}}
|
||||
@@ -26,4 +26,5 @@ Hugo と Hextra が提供する追加のショートコード:
|
||||
{{< cards >}}
|
||||
{{< card link="jupyter" title="Jupyter Notebook" icon="jupyter" tag="alpha" >}}
|
||||
{{< card link="others" title="Others" icon="view-grid" >}}
|
||||
{{< card link="asciinema" title="Asciinema Player" icon="terminal" >}}
|
||||
{{< /cards >}}
|
||||
@@ -27,4 +27,5 @@ Additional shortcodes provided by Hugo and Hextra:
|
||||
{{< card link="jupyter" title="Jupyter Notebook" icon="jupyter" tag="alpha" >}}
|
||||
{{< card link="others" title="Others" icon="view-grid" >}}
|
||||
{{< card link="hextra" title="Hextra" icon="view-grid" >}}
|
||||
{{< card link="asciinema" title="Asciinema Player" icon="terminal" >}}
|
||||
{{< /cards >}}
|
||||
|
||||
@@ -26,4 +26,5 @@ Hugo 和 Hextra 提供的其他短代码：
|
||||
{{< cards >}}
|
||||
{{< card link="jupyter" title="Jupyter 笔记本" icon="jupyter" tag="alpha" >}}
|
||||
{{< card link="others" title="其他" icon="view-grid" >}}
|
||||
{{< card link="asciinema" title="Asciinema Player" icon="terminal" >}}
|
||||
{{< /cards >}}
|
||||
121
exampleSite/content/docs/guide/shortcodes/asciinema.fa.md
Normal file
121
exampleSite/content/docs/guide/shortcodes/asciinema.fa.md
Normal file
@@ -0,0 +1,121 @@
|
||||
---
|
||||
title: "Asciinema Player کامپوننت"
|
||||
linktitle: "Asciinema Player"
|
||||
sidebar:
|
||||
exclude: true
|
||||
---
|
||||
|
||||
shortcode asciinema به شما امکان می‌دهد تا ضبط‌های ترمینال ایجاد شده با [asciinema](https://asciinema.org/) را در سایت Hugo خود جاسازی کنید. این یک پخش‌کننده ترمینال غنی با ویژگی‌هایی مانند کنترل پخش، تنظیم سرعت و سفارشی‌سازی تم ارائه می‌دهد.
|
||||
|
||||
## استفاده پایه
|
||||
|
||||
shortcode asciinema از فایل‌های `.cast` محلی و URL های راه دور پشتیبانی می‌کند. روش‌های مختلف استفاده از فایل‌های محلی به شرح زیر است:
|
||||
|
||||
### فایل‌های محلی
|
||||
|
||||
**روش 1: دایرکتوری Assets (توصیه شده)**
|
||||
فایل‌های cast را در دایرکتوری `assets/` سایت Hugo خود قرار دهید:
|
||||
|
||||
```
|
||||
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" >}}
|
||||
|
||||
### فایل‌های راه دور
|
||||
|
||||
همچنین می‌توانید از فایل‌های cast از هر URL راه دور استفاده کنید:
|
||||
|
||||
```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") |
|
||||
121
exampleSite/content/docs/guide/shortcodes/asciinema.ja.md
Normal file
121
exampleSite/content/docs/guide/shortcodes/asciinema.ja.md
Normal file
@@ -0,0 +1,121 @@
|
||||
---
|
||||
title: "Asciinema Player コンポーネント"
|
||||
linktitle: "Asciinema Player"
|
||||
sidebar:
|
||||
exclude: true
|
||||
---
|
||||
|
||||
asciinema shortcode を使用すると、[asciinema](https://asciinema.org/) で作成されたターミナル録画を Hugo サイトに埋め込むことができます。再生制御、速度調整、テーマカスタマイズなどの機能を備えたリッチなターミナルプレイヤーを提供します。
|
||||
|
||||
## 基本的な使用方法
|
||||
|
||||
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"） |
|
||||
124
exampleSite/content/docs/guide/shortcodes/asciinema.md
Normal file
124
exampleSite/content/docs/guide/shortcodes/asciinema.md
Normal file
@@ -0,0 +1,124 @@
|
||||
---
|
||||
title: "Asciinema Player Component"
|
||||
linktitle: "Asciinema Player"
|
||||
sidebar:
|
||||
exclude: true
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The asciinema shortcode allows you to embed terminal recordings created with [asciinema](https://asciinema.org/) 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:
|
||||
```markdown
|
||||
{{</* 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:
|
||||
```markdown
|
||||
{{</* 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:
|
||||
```markdown
|
||||
{{</* asciinema file="demo.cast" */>}}
|
||||
```
|
||||
|
||||
{{< asciinema file="casts/demo.cast" >}}
|
||||
|
||||
### Remote Files
|
||||
|
||||
You can also use cast files from any remote URL:
|
||||
|
||||
```markdown
|
||||
{{</* asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" */>}}
|
||||
{{</* asciinema file="https://example.com/demo.cast" */>}}
|
||||
```
|
||||
|
||||
{{< asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.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:
|
||||
|
||||
```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"
|
||||
>}}
|
||||
|
||||
## Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `file` | string | - | Path to the .cast file (required). Supports local files, absolute paths, and remote URLs |
|
||||
| `theme` | string | `"asciinema"` | Player theme |
|
||||
| `speed` | number | `1` | Playback speed multiplier |
|
||||
| `autoplay` | boolean | `false` | Start playing automatically |
|
||||
| `loop` | boolean | `false` | Loop the recording |
|
||||
| `poster` | string | `""` | Poster (a preview frame) to display until the playback is started. Supports NPT notation (e.g., "npt:1:23") |
|
||||
| `markers` | string | `""` | Comma-separated time markers. Format: "time:label" or just "time" (e.g., "1.5:Installation,3.2:Configuration,5.8") |
|
||||
|
||||
121
exampleSite/content/docs/guide/shortcodes/asciinema.zh-cn.md
Normal file
121
exampleSite/content/docs/guide/shortcodes/asciinema.zh-cn.md
Normal file
@@ -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"） |
|
||||
Reference in New Issue
Block a user