feat(shortcodes): add video shortcode

2026-01-30 16:31:52 +01:00 · 2025-12-27 18:42:04 +08:00
parent 94fdf4fded
commit ef9486f794
11 changed files with 659 additions and 0 deletions
--- a/exampleSite/content/docs/shortcodes/index.de.md
+++ b/exampleSite/content/docs/shortcodes/index.de.md
@@ -981,6 +981,54 @@ consectetur adipiscing elit.

 <br/><br/><br/>

+## Video
+
+Blowfish enthält einen `video`-Shortcode, um lokale oder externe Videos in Inhalte einzubetten. Der Shortcode rendert einen `<figure>`-Wrapper mit einem responsiven Videoplayer und einer optionalen Bildunterschrift.
+
+Der `video`-Shortcode akzeptiert die folgenden Parameter:
+
+<!-- prettier-ignore-start -->
+| Parameter | Beschreibung |
+| --- | --- |
+| `src` | **Erforderlich.** Video-URL oder lokaler Pfad. Lokale Suchreihenfolge: Seitenressource → `assets/` → `static/`. |
+| `poster` | Optionales Posterbild (URL oder lokaler Pfad). Wenn nicht gesetzt, versucht der Shortcode ein gleichnamiges Bild im Page Bundle zu finden. |
+| `caption` | Optionale Markdown-Bildunterschrift unter dem Video. |
+| `autoplay` | `true`/`false`. Aktiviert Autoplay, wenn `true`. Standard: `false`. |
+| `loop` | `true`/`false`. Wiederholt bei `true`. Standard: `false`. |
+| `muted` | `true`/`false`. Stumm, wenn `true`. Standard: `false`. |
+| `controls` | `true`/`false`. Zeigt die standardmäßigen Browser-Steuerelemente, wenn `true`. Standard: `true`. |
+| `playsinline` | `true`/`false`. Inline-Wiedergabe auf Mobilgeräten bei `true`. Standard: `true`. |
+| `preload` | `metadata` (lädt Infos), `none` (spart Bandbreite) oder `auto` (lädt mehr vor). Standard: `metadata`. |
+| `start` | Optionale Startzeit in Sekunden. |
+| `end` | Optionale Endzeit in Sekunden. |
+| `ratio` | Reserviertes Seitenverhältnis für den Player. Unterstützt `16/9`, `4/3`, `1/1` oder benutzerdefiniertes `W/H`. Standard: `16/9`. |
+| `fit` | Wie das Video in das Verhältnis passt: `contain` (kein Zuschnitt), `cover` (füllend zuschneiden), `fill` (strecken). Standard: `contain`. |
+<!-- prettier-ignore-end -->
+
+Wenn der Browser das Video nicht abspielen kann, zeigt der Player einen kurzen englischen Hinweis mit einem Download-Link.
+
+**Beispiel:**
+
+```md
+{{</* video
+    src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
+    poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
+    caption="**Public-Domain-Demo** — CC0-Video und Poster."
+    loop=true
+    muted=true
+*/>}}
+```
+
+{{< video
+  src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
+  poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
+  caption="**Public-Domain-Demo** — CC0-Video und Poster."
+  loop=true
+  muted=true
+>}}
+
+<br/><br/><br/>
+
 ## Youtube Lite

 Eine Verknüpfung zum Einbetten von YouTube-Videos mit der [lite-youtube-embed](https://github.com/paulirish/lite-youtube-embed)-Bibliothek. Diese Bibliothek ist eine leichtgewichtige Alternative zu den Standard-YouTube-Einbettungen und wurde für Geschwindigkeit und Effizienz entwickelt.
--- a/exampleSite/content/docs/shortcodes/index.es.md
+++ b/exampleSite/content/docs/shortcodes/index.es.md
@@ -981,6 +981,54 @@ consectetur adipiscing elit.

 <br/><br/><br/>

+## Video
+
+Blowfish incluye un shortcode `video` para incrustar vídeos locales o externos en el contenido. El shortcode renderiza un contenedor `<figure>` con un reproductor de vídeo adaptable y un pie de foto opcional.
+
+El shortcode `video` acepta los siguientes parámetros:
+
+<!-- prettier-ignore-start -->
+| Parámetro | Descripción |
+| --- | --- |
+| `src` | **Requerido.** URL del vídeo o ruta local. Orden de búsqueda local: recurso de página → `assets/` → `static/`. |
+| `poster` | Imagen de póster opcional (URL o ruta local). Si se omite, el shortcode intenta una imagen con el mismo nombre en el bundle de la página. |
+| `caption` | Pie de foto opcional en Markdown, mostrado debajo del vídeo. |
+| `autoplay` | `true`/`false`. Activa la reproducción automática cuando es `true`. Predeterminado: `false`. |
+| `loop` | `true`/`false`. Repite en bucle cuando es `true`. Predeterminado: `false`. |
+| `muted` | `true`/`false`. Silencia cuando es `true`. Predeterminado: `false`. |
+| `controls` | `true`/`false`. Muestra los controles de reproducción predeterminados del navegador cuando es `true`. Predeterminado: `true`. |
+| `playsinline` | `true`/`false`. Reproducción en línea en móvil cuando es `true`. Predeterminado: `true`. |
+| `preload` | `metadata` (carga info), `none` (ahorra ancho de banda) o `auto` (precarga más). Predeterminado: `metadata`. |
+| `start` | Tiempo de inicio opcional en segundos. |
+| `end` | Tiempo de fin opcional en segundos. |
+| `ratio` | Relación de aspecto reservada para el reproductor. Soporta `16/9`, `4/3`, `1/1` o `W/H` personalizado. Predeterminado: `16/9`. |
+| `fit` | Cómo encaja el vídeo en la relación: `contain` (sin recorte), `cover` (recorta para llenar), `fill` (estira). Predeterminado: `contain`. |
+<!-- prettier-ignore-end -->
+
+Si el navegador no puede reproducir el vídeo, el reproductor mostrará un breve mensaje en inglés con un enlace de descarga.
+
+**Ejemplo:**
+
+```md
+{{</* video
+    src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
+    poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
+    caption="**Demo de dominio público** — vídeo y póster CC0."
+    loop=true
+    muted=true
+*/>}}
+```
+
+{{< video
+  src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
+  poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
+  caption="**Demo de dominio público** — vídeo y póster CC0."
+  loop=true
+  muted=true
+>}}
+
+<br/><br/><br/>
+
 ## Youtube Lite

 Un atajo para incrustar videos de YouTube usando la biblioteca [lite-youtube-embed](https://github.com/paulirish/lite-youtube-embed). Esta biblioteca es una alternativa ligera a las incrustaciones estándar de YouTube, y está diseñada para ser más rápida y eficiente.
--- a/exampleSite/content/docs/shortcodes/index.fr.md
+++ b/exampleSite/content/docs/shortcodes/index.fr.md
@@ -981,6 +981,54 @@ consectetur adipiscing elit.

 <br/><br/><br/>

+## Video
+
+Blowfish inclut un shortcode `video` pour intégrer des vidéos locales ou externes dans le contenu. Le shortcode génère un conteneur `<figure>` avec un lecteur vidéo adaptatif et une légende facultative.
+
+Le shortcode `video` accepte les paramètres suivants :
+
+<!-- prettier-ignore-start -->
+| Paramètre | Description |
+| --- | --- |
+| `src` | **Requis.** URL de la vidéo ou chemin local. Ordre de recherche local : ressource de page → `assets/` → `static/`. |
+| `poster` | Image d'affiche optionnelle (URL ou chemin local). Si omise, le shortcode tente une image du même nom dans le bundle de page. |
+| `caption` | Légende Markdown optionnelle affichée sous la vidéo. |
+| `autoplay` | `true`/`false`. Active la lecture automatique quand `true`. Par défaut : `false`. |
+| `loop` | `true`/`false`. Boucle quand `true`. Par défaut : `false`. |
+| `muted` | `true`/`false`. Met en sourdine quand `true`. Par défaut : `false`. |
+| `controls` | `true`/`false`. Affiche les contrôles de lecture par défaut du navigateur quand `true`. Par défaut : `true`. |
+| `playsinline` | `true`/`false`. Lecture en ligne sur mobile quand `true`. Par défaut : `true`. |
+| `preload` | `metadata` (charge les infos), `none` (économise la bande passante) ou `auto` (précharge davantage). Par défaut : `metadata`. |
+| `start` | Temps de début optionnel en secondes. |
+| `end` | Temps de fin optionnel en secondes. |
+| `ratio` | Ratio d'aspect réservé pour le lecteur. Prend en charge `16/9`, `4/3`, `1/1` ou `W/H` personnalisé. Par défaut : `16/9`. |
+| `fit` | Ajustement de la vidéo dans le ratio : `contain` (pas de recadrage), `cover` (recadre pour remplir), `fill` (étire). Par défaut : `contain`. |
+<!-- prettier-ignore-end -->
+
+Si le navigateur ne peut pas lire la vidéo, le lecteur affiche un message minimal en anglais avec un lien de téléchargement.
+
+**Exemple :**
+
+```md
+{{</* video
+    src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
+    poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
+    caption="**Démo du domaine public** — vidéo et affiche CC0."
+    loop=true
+    muted=true
+*/>}}
+```
+
+{{< video
+  src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
+  poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
+  caption="**Démo du domaine public** — vidéo et affiche CC0."
+  loop=true
+  muted=true
+>}}
+
+<br/><br/><br/>
+
 ## Youtube Lite

 Un raccourci pour intégrer des vidéos YouTube en utilisant la bibliothèque [lite-youtube-embed](https://github.com/paulirish/lite-youtube-embed). Cette bibliothèque est une alternative légère aux intégrations YouTube standard, et elle est conçue pour être plus rapide et plus efficace.
--- a/exampleSite/content/docs/shortcodes/index.it.md
+++ b/exampleSite/content/docs/shortcodes/index.it.md
@@ -981,6 +981,54 @@ consectetur adipiscing elit.

 <br/><br/><br/>

+## Video
+
+Blowfish include uno shortcode `video` per incorporare video locali o esterni nei contenuti. Lo shortcode renderizza un contenitore `<figure>` con un lettore video responsive e una didascalia opzionale.
+
+Lo shortcode `video` accetta i seguenti parametri:
+
+<!-- prettier-ignore-start -->
+| Parametro | Descrizione |
+| --- | --- |
+| `src` | **Obbligatorio.** URL del video o percorso locale. Ordine di ricerca locale: risorsa di pagina → `assets/` → `static/`. |
+| `poster` | Immagine poster opzionale (URL o percorso locale). Se omessa, lo shortcode tenta un'immagine con lo stesso nome nel bundle della pagina. |
+| `caption` | Didascalia Markdown opzionale mostrata sotto il video. |
+| `autoplay` | `true`/`false`. Attiva la riproduzione automatica quando `true`. Predefinito: `false`. |
+| `loop` | `true`/`false`. Ripete in loop quando `true`. Predefinito: `false`. |
+| `muted` | `true`/`false`. Silenzia quando `true`. Predefinito: `false`. |
+| `controls` | `true`/`false`. Mostra i controlli di riproduzione predefiniti del browser quando `true`. Predefinito: `true`. |
+| `playsinline` | `true`/`false`. Riproduzione in linea su mobile quando `true`. Predefinito: `true`. |
+| `preload` | `metadata` (carica le info), `none` (risparmia banda) o `auto` (precarica di più). Predefinito: `metadata`. |
+| `start` | Tempo di inizio opzionale in secondi. |
+| `end` | Tempo di fine opzionale in secondi. |
+| `ratio` | Rapporto d'aspetto riservato per il lettore. Supporta `16/9`, `4/3`, `1/1` o `W/H` personalizzato. Predefinito: `16/9`. |
+| `fit` | Come il video si adatta al rapporto: `contain` (senza ritaglio), `cover` (ritaglia per riempire), `fill` (stira). Predefinito: `contain`. |
+<!-- prettier-ignore-end -->
+
+Se il browser non riesce a riprodurre il video, il lettore mostrerà un breve messaggio in inglese con un link per il download.
+
+**Esempio:**
+
+```md
+{{</* video
+    src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
+    poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
+    caption="**Demo di pubblico dominio** — video e poster CC0."
+    loop=true
+    muted=true
+*/>}}
+```
+
+{{< video
+  src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
+  poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
+  caption="**Demo di pubblico dominio** — video e poster CC0."
+  loop=true
+  muted=true
+>}}
+
+<br/><br/><br/>
+
 ## Youtube Lite

 A shortcut to embed youtube videos using the [lite-youtube-embed](https://github.com/paulirish/lite-youtube-embed) library. This library is a lightweight alternative to the standard youtube embeds, and it's designed to be faster and more efficient.
--- a/exampleSite/content/docs/shortcodes/index.ja.md
+++ b/exampleSite/content/docs/shortcodes/index.ja.md
@@ -977,6 +977,54 @@ consectetur adipiscing elit.

 <br/><br/><br/>

+## Video
+
+Blowfish には、ローカルまたは外部の動画を本文に埋め込むための `video` ショートコードがあります。ショートコードは `<figure>` で包んだレスポンシブな動画プレーヤーと、任意のキャプションを出力します。
+
+`video` ショートコードは次のパラメータを受け取ります:
+
+<!-- prettier-ignore-start -->
+| パラメータ | 説明 |
+| --- | --- |
+| `src` | **必須。** 動画のURLまたはローカルパス。ローカルの検索順: ページリソース → `assets/` → `static/`。 |
+| `poster` | 任意のポスター画像URLまたはローカルパス。省略時は、ページバンドル内で同名の画像を試します。 |
+| `caption` | 動画下に表示するMarkdownキャプション（任意）。 |
+| `autoplay` | `true`/`false`。`true` で自動再生。既定: `false`。 |
+| `loop` | `true`/`false`。`true` でループ再生。既定: `false`。 |
+| `muted` | `true`/`false`。`true` でミュート。既定: `false`。 |
+| `controls` | `true`/`false`。`true` でブラウザ標準の再生コントロールを表示。既定: `true`。 |
+| `playsinline` | `true`/`false`。`true` でモバイルのインライン再生。既定: `true`。 |
+| `preload` | `metadata`（情報のみ読み込み）、`none`（帯域節約）、`auto`（より多く事前読み込み）。既定: `metadata`。 |
+| `start` | 任意の開始秒。 |
+| `end` | 任意の終了秒。 |
+| `ratio` | プレーヤーの予約アスペクト比。`16/9`、`4/3`、`1/1`、またはカスタム `W/H` に対応。既定: `16/9`。 |
+| `fit` | 比率への収まり方: `contain`（切り抜きなし）、`cover`（切り抜いて埋める）、`fill`（引き伸ばす）。既定: `contain`。 |
+<!-- prettier-ignore-end -->
+
+ブラウザが動画を再生できない場合、プレーヤーは英語の簡潔なフォールバック文とダウンロードリンクを表示します。
+
+**例:**
+
+```md
+{{</* video
+    src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
+    poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
+    caption="**パブリックドメインのデモ** — CC0 の動画とポスター。"
+    loop=true
+    muted=true
+*/>}}
+```
+
+{{< video
+  src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
+  poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
+  caption="**パブリックドメインのデモ** — CC0 の動画とポスター。"
+  loop=true
+  muted=true
+>}}
+
+<br/><br/><br/>
+
 ## Youtube Lite

 [lite-youtube-embed](https://github.com/paulirish/lite-youtube-embed) ライブラリを使用して YouTube 動画を埋め込むためのショートカット。このライブラリは、標準の YouTube 埋め込みの軽量な代替手段であり、より高速で効率的になるように設計されています。
--- a/exampleSite/content/docs/shortcodes/index.md
+++ b/exampleSite/content/docs/shortcodes/index.md
@@ -981,6 +981,54 @@ consectetur adipiscing elit.

 <br/><br/><br/>

+## Video
+
+Blowfish includes a `video` shortcode for embedding local or external videos in content. The shortcode renders a `<figure>` wrapper with a responsive video player and an optional caption.
+
+The `video` shortcode accepts the following parameters:
+
+<!-- prettier-ignore-start -->
+| Parameter | Description |
+| --- | --- |
+| `src` | **Required.** Video URL or local path. Local lookup order: page resource → `assets/` → `static/`. |
+| `poster` | Optional poster image URL or local path. If omitted, the shortcode attempts a same-name image in the page bundle. |
+| `caption` | Optional Markdown caption shown below the video. |
+| `autoplay` | `true`/`false`. Enables autoplay when `true`. Default: `false`. |
+| `loop` | `true`/`false`. Loops when `true`. Default: `false`. |
+| `muted` | `true`/`false`. Mutes when `true`. Default: `false`. |
+| `controls` | `true`/`false`. Shows the browser’s default playback controls when `true`. Default: `true`. |
+| `playsinline` | `true`/`false`. Inline playback on mobile when `true`. Default: `true`. |
+| `preload` | `metadata` (load info), `none` (save bandwidth), or `auto` (preload more). Default: `metadata`. |
+| `start` | Optional start time in seconds. |
+| `end` | Optional end time in seconds. |
+| `ratio` | Reserved aspect ratio for the player. Supports `16/9`, `4/3`, `1/1`, or custom `W/H`. Default: `16/9`. |
+| `fit` | How the video fits the ratio: `contain` (no crop), `cover` (crop to fill), `fill` (stretch). Default: `contain`. |
+<!-- prettier-ignore-end -->
+
+If the browser cannot play the video, the player will show a minimal English fallback message with a download link.
+
+**Example:**
+
+```md
+{{</* video
+    src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
+    poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
+    caption="**Public domain demo** — CC0 video and poster."
+    loop=true
+    muted=true
+*/>}}
+```
+
+{{< video
+  src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
+  poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
+  caption="**Public domain demo** — CC0 video and poster."
+  loop=true
+  muted=true
+>}}
+
+<br/><br/><br/>
+
 ## Youtube Lite

 A shortcut to embed youtube videos using the [lite-youtube-embed](https://github.com/paulirish/lite-youtube-embed) library. This library is a lightweight alternative to the standard youtube embeds, and it's designed to be faster and more efficient.
--- a/exampleSite/content/docs/shortcodes/index.pt-br.md
+++ b/exampleSite/content/docs/shortcodes/index.pt-br.md
@@ -981,6 +981,54 @@ consectetur adipiscing elit.

 <br/><br/><br/>

+## Video
+
+Blowfish inclui um shortcode `video` para incorporar vídeos locais ou externos no conteúdo. O shortcode renderiza um contêiner `<figure>` com um player de vídeo responsivo e uma legenda opcional.
+
+O shortcode `video` aceita os seguintes parâmetros:
+
+<!-- prettier-ignore-start -->
+| Parâmetro | Descrição |
+| --- | --- |
+| `src` | **Obrigatório.** URL do vídeo ou caminho local. Ordem de busca local: recurso da página → `assets/` → `static/`. |
+| `poster` | Imagem de pôster opcional (URL ou caminho local). Se omitida, o shortcode tenta uma imagem com o mesmo nome no bundle da página. |
+| `caption` | Legenda opcional em Markdown exibida abaixo do vídeo. |
+| `autoplay` | `true`/`false`. Ativa a reprodução automática quando `true`. Padrão: `false`. |
+| `loop` | `true`/`false`. Reproduz em loop quando `true`. Padrão: `false`. |
+| `muted` | `true`/`false`. Silencia quando `true`. Padrão: `false`. |
+| `controls` | `true`/`false`. Mostra os controles de reprodução padrão do navegador quando `true`. Padrão: `true`. |
+| `playsinline` | `true`/`false`. Reprodução inline em dispositivos móveis quando `true`. Padrão: `true`. |
+| `preload` | `metadata` (carrega informações), `none` (economiza banda) ou `auto` (pré-carrega mais). Padrão: `metadata`. |
+| `start` | Tempo de início opcional em segundos. |
+| `end` | Tempo de fim opcional em segundos. |
+| `ratio` | Proporção reservada para o player. Suporta `16/9`, `4/3`, `1/1` ou `W/H` personalizado. Padrão: `16/9`. |
+| `fit` | Como o vídeo se ajusta à proporção: `contain` (sem corte), `cover` (corta para preencher), `fill` (estica). Padrão: `contain`. |
+<!-- prettier-ignore-end -->
+
+Se o navegador não puder reproduzir o vídeo, o player exibirá uma mensagem mínima em inglês com um link para download.
+
+**Exemplo:**
+
+```md
+{{</* video
+    src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
+    poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
+    caption="**Demo de domínio público** — vídeo e pôster CC0."
+    loop=true
+    muted=true
+*/>}}
+```
+
+{{< video
+  src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
+  poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
+  caption="**Demo de domínio público** — vídeo e pôster CC0."
+  loop=true
+  muted=true
+>}}
+
+<br/><br/><br/>
+
 ## Youtube Lite

 Um atalho para incorporar vídeos do YouTube usando a biblioteca [lite-youtube-embed](https://github.com/paulirish/lite-youtube-embed). Esta biblioteca é uma alternativa leve aos embeds padrão do YouTube, e é projetada para ser mais rápida e eficiente.
--- a/exampleSite/content/docs/shortcodes/index.pt-pt.md
+++ b/exampleSite/content/docs/shortcodes/index.pt-pt.md
@@ -981,6 +981,54 @@ consectetur adipiscing elit.

 <br/><br/><br/>

+## Video
+
+Blowfish inclui um shortcode `video` para incorporar vídeos locais ou externos no conteúdo. O shortcode renderiza um contentor `<figure>` com um player de vídeo responsivo e uma legenda opcional.
+
+O shortcode `video` aceita os seguintes parâmetros:
+
+<!-- prettier-ignore-start -->
+| Parâmetro | Descrição |
+| --- | --- |
+| `src` | **Obrigatório.** URL do vídeo ou caminho local. Ordem de pesquisa local: recurso da página → `assets/` → `static/`. |
+| `poster` | Imagem de póster opcional (URL ou caminho local). Se omitida, o shortcode tenta uma imagem com o mesmo nome no bundle da página. |
+| `caption` | Legenda opcional em Markdown apresentada abaixo do vídeo. |
+| `autoplay` | `true`/`false`. Ativa a reprodução automática quando `true`. Padrão: `false`. |
+| `loop` | `true`/`false`. Reproduz em loop quando `true`. Padrão: `false`. |
+| `muted` | `true`/`false`. Silencia quando `true`. Padrão: `false`. |
+| `controls` | `true`/`false`. Mostra os controlos de reprodução padrão do navegador quando `true`. Padrão: `true`. |
+| `playsinline` | `true`/`false`. Reprodução inline em dispositivos móveis quando `true`. Padrão: `true`. |
+| `preload` | `metadata` (carrega informações), `none` (poupa largura de banda) ou `auto` (pré-carrega mais). Padrão: `metadata`. |
+| `start` | Tempo de início opcional em segundos. |
+| `end` | Tempo de fim opcional em segundos. |
+| `ratio` | Proporção reservada para o player. Suporta `16/9`, `4/3`, `1/1` ou `W/H` personalizado. Padrão: `16/9`. |
+| `fit` | Como o vídeo se ajusta à proporção: `contain` (sem corte), `cover` (corta para preencher), `fill` (estica). Padrão: `contain`. |
+<!-- prettier-ignore-end -->
+
+Se o navegador não conseguir reproduzir o vídeo, o player apresentará uma mensagem mínima em inglês com um link de download.
+
+**Exemplo:**
+
+```md
+{{</* video
+    src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
+    poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
+    caption="**Demo de domínio público** — vídeo e póster CC0."
+    loop=true
+    muted=true
+*/>}}
+```
+
+{{< video
+  src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
+  poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
+  caption="**Demo de domínio público** — vídeo e póster CC0."
+  loop=true
+  muted=true
+>}}
+
+<br/><br/><br/>
+
 ## Youtube Lite

 Um atalho para incorporar vídeos do YouTube utilizando a biblioteca [lite-youtube-embed](https://github.com/paulirish/lite-youtube-embed). Esta biblioteca é uma alternativa leve aos embeds padrão do YouTube, e foi concebida para ser mais rápida e eficiente.
--- a/exampleSite/content/docs/shortcodes/index.zh-cn.md
+++ b/exampleSite/content/docs/shortcodes/index.zh-cn.md
@@ -994,6 +994,54 @@ consectetur adipiscing elit.
 {{< /typeit >}}


+<br/><br/><br/>
+
+## Video
+
+Blowfish 提供 `video` 简码，用于在内容中嵌入本地或外部视频。该简码会渲染一个 `<figure>` 容器，包含自适应的视频播放器和可选说明。
+
+`video` 简码支持以下参数：
+
+<!-- prettier-ignore-start -->
+| 参数 | 说明 |
+| --- | --- |
+| `src` | **必填。** 视频 URL 或本地路径。本地查找顺序：页面资源 → `assets/` → `static/`。 |
+| `poster` | 可选的封面图 URL 或本地路径。未提供时，会尝试在页面 bundle 中寻找同名图片。 |
+| `caption` | 可选的 Markdown 说明文字，显示在视频下方。 |
+| `autoplay` | `true`/`false`。为 `true` 时自动播放。默认：`false`。 |
+| `loop` | `true`/`false`。为 `true` 时循环播放。默认：`false`。 |
+| `muted` | `true`/`false`。为 `true` 时静音。默认：`false`。 |
+| `controls` | `true`/`false`。为 `true` 时显示浏览器默认播放控制条。默认：`true`。 |
+| `playsinline` | `true`/`false`。为 `true` 时在移动端内联播放。默认：`true`。 |
+| `preload` | `metadata`（仅加载信息）、`none`（节省带宽）或 `auto`（预加载更多）。默认：`metadata`。 |
+| `start` | 可选的开始时间（秒）。 |
+| `end` | 可选的结束时间（秒）。 |
+| `ratio` | 为播放器预留的宽高比。支持 `16/9`、`4/3`、`1/1` 或自定义 `W/H`。默认：`16/9`。 |
+| `fit` | 视频在比例中的适配方式：`contain`（不裁切）、`cover`（裁切填满）、`fill`（拉伸）。默认：`contain`。 |
+<!-- prettier-ignore-end -->
+
+如果浏览器无法播放视频，播放器会显示一段简短的英文提示并提供下载链接。
+
+**示例：**
+
+```md
+{{</* video
+    src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
+    poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
+    caption="**公有领域演示** — CC0 视频与封面。"
+    loop=true
+    muted=true
+*/>}}
+```
+
+{{< video
+  src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
+  poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
+  caption="**公有领域演示** — CC0 视频与封面。"
+  loop=true
+  muted=true
+>}}
+
 <br/><br/><br/>

 ## Youtube 嵌入播放器