嵌入元素速查:视频、推文、二维码、图片、代码
把可以塞进 markdown 的各种媒体元素跑一遍,确认主题的渲染效果。
写博客时除了文字和图片,还经常要嵌入视频、推文、二维码这些"非文本"内容。Hugo 的 shortcode 机制让这些嵌入都能用一行简洁的语法搞定。下面把这个主题支持的全部嵌入元素演示一遍。
一、YouTube 视频
Hugo 内置 youtube shortcode,只要把视频 ID 喂进去(URL 里 v= 后面那串):
{{< youtube aqz-KE-bpKQ >}}
效果:
自动 16:9 比例响应式,移动端也会自适应。
二、Vimeo 视频
同理,vimeo shortcode 接受视频 ID:
{{< vimeo 76979871 >}}
Vimeo 的嵌入界面比 YouTube 干净一些,适合纯作品展示。
三、X / Twitter 推文
通过 url 参数嵌入完整推文(会自动渲染头像、内容、互动数据):
{{< x url="https://x.com/twitter/status/1228393702244134912" >}}
也可以拆开传:
{{< x user="twitter" id="1228393702244134912" >}}
实际效果(需要联网加载 X 的 widgets.js):
⚠️ 如果你的访问受限(如国内不挂梯子),X 的 widgets.js 加载会失败,推文会显示为一个简单的"查看推文"链接。这是预期行为,不影响其他内容。
四、二维码
qr shortcode 即时生成二维码图(通过公共 API)。常用于"扫码加微信 / 关注公众号 / 下载 App"等场景:
{{< qr text="https://zero9501.online" size="180" caption="扫码访问博客" >}}
参数:
| 参数 | 默认 | 说明 |
|---|---|---|
text | 无 | 必填,要编码的内容(URL / 文本 / WiFi 配置 / vCard 等) |
size | 200 | 像素尺寸 |
caption | 无 | 图下方说明文字 |
五、图片排布
详细用法见之前那篇 图片排布速查,这里再快速过一遍。
单张全幅大图
{{< wide src="https://picsum.photos/id/29/2000/900" caption="一张需要呼吸感的风景" >}}
双联横排
九宫格
六、语言代码块
```language 围栏后跟语言名即可,主题会自动渲染语法高亮 + macOS 终端风装饰条 + 复制按钮。
Python
from dataclasses import dataclass
@dataclass
class Article:
title: str
word_count: int
def reading_minutes(self) -> int:
# 按 500 字/分钟估算(中文阅读速度)
return max(1, self.word_count // 500)
if __name__ == "__main__":
a = Article(title="嵌入元素速查", word_count=1200)
print(f"{a.title} - 约 {a.reading_minutes()} 分钟")
Rust
use std::time::Duration;
/// 单次重试间隔(指数退避)
fn backoff(attempt: u32) -> Duration {
let base = 200u64;
let ms = base.saturating_mul(2u64.saturating_pow(attempt));
Duration::from_millis(ms.min(30_000))
}
fn main(){
assert!(backoff(0) < backoff(3));
}
Go
package main
import (
"fmt"
"time"
)
type Post struct {
Title string
Published time.Time
}
func (p Post) Age() time.Duration {
return time.Since(p.Published)
}
func main() {
p := Post{Title: "Hello", Published: time.Now().Add(-72 * time.Hour)}
fmt.Printf("%q 发布了 %.0f 小时\n", p.Title, p.Age().Hours())
}
TypeScript
type Result<T, E = Error> =
| { ok: true; value: T }
| { ok: false; error: E };
async function fetchJson<T>(url: string): Promise<Result<T>> {
try {
const res = await fetch(url);
if (!res.ok) {
return { ok: false, error: new Error(`HTTP ${res.status}`) };
}
return { ok: true, value: (await res.json()) as T };
} catch (e) {
return { ok: false, error: e as Error };
}
}
Shell
#!/usr/bin/env bash
set -euo pipefail
# 部署博客:构建 + 推送
hugo --gc --minify
git add public/ content/
git commit -m "post: 新文章"
git push
SQL
-- 找出本月发表的、阅读数前 10 的文章
SELECT title, views, published_at
FROM posts
WHERE published_at >= date_trunc('month', current_date)
ORDER BY views DESC
LIMIT 10;
无语言名(纯文本,仍带装饰条但无颜色):
+----------+ +-----------+
| Author | ---> | Markdown |
+----------+ +-----------+
|
v
+-----------+
| Hugo |
+-----------+
多语言标签栏
同一段逻辑的多语言实现,用 tabs / tab 包裹,点标签切换。每组的标签名和数量随意,互不联动:
{{< tabs >}}
{{< tab "Java" >}}
(普通 Markdown 代码围栏)
{{< /tab >}}
{{< tab "Kotlin" >}}
(普通 Markdown 代码围栏)
{{< /tab >}}
{{< /tabs >}}
public class Main {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
fun main() {
println("Hello, World!")
}
package main
import "fmt"
func main() {
fmt.Println("Hello, World!")
}
七、行内嵌入:链接 / 图标 / 按键
正文里也能嵌入小元素:
- 行内代码:使用
git rebase -i HEAD~3合并提交 - 键盘:Cmd + Shift + P 打开命令面板
- 链接:访问 Hugo 官网
- 缩写:HTML 鼠标悬停看说明
八、嵌入的几个共性
| 元素 | 是否依赖外部网络 | 是否影响 SEO |
|---|---|---|
| YouTube / Vimeo | 是 | 不影响 |
| X 推文 | 是 | 不影响 |
| 二维码 | 是(首次) | 不影响 |
| 图片(外链) | 是 | 与图床有关 |
| 代码块 | 否 | 良好 |
所有嵌入都用了 loading="lazy" 或 async,不会阻塞首屏渲染。代码块的复制按钮是纯前端实现,零依赖。
到这儿就把这个主题里能塞进 markdown 的"非文本"内容都展示完了。写作时按需用即可——不是每篇文章都需要这么花,多数情况下文字 + 一两张图就够。
九、音乐播放器
站内默认开启全局播放器(左下角横条),单篇文章里也可以嵌入专属播放器,或者用纯背景音乐模式。
播放平台歌单 / 单曲
aplayer shortcode 对接主流平台,无需 API Key,传 ID 即可:
{{< aplayer server="tencent" type="playlist" id="7798160336" >}}
效果:
参数:
| 参数 | 默认 | 说明 |
|---|---|---|
server | netease | 平台:netease(网易云) / tencent(QQ) / kugou / xiami / baidu |
type | song | song(单曲) / playlist(歌单) / album(专辑) / artist(歌手) / search(关键词) |
id | 必填 | 平台对应的 ID 或搜索词 |
mini | false | 极简模式,只显示一行,省空间 |
autoplay | false | 自动播放(浏览器一般会拦) |
theme | #2980b9 | 主题色(进度条、按钮 hover 等) |
loop | all | all 列表循环 / one 单曲循环 / none 不循环 |
order | list | list 顺序 / random 随机 |
volume | 0.7 | 0~1,初始音量 |
listFolded | false | 播放列表默认折叠 |
fixed | false | 固定在左下角横条(文章内不建议开,会与全局播放器重叠) |
播放自定义单曲
url 直接指向音频文件(如 R2 / 自建图床),无需平台 ID:
{{< aplayer
name="风继续吹"
artist="张国荣"
url="https://cdn.zero9501.online/music/feng.mp3"
cover="https://cdn.zero9501.online/cover/feng.jpg"
>}}
效果:
自定义模式新增以下参数(其余通用参数同上):
| 参数 | 默认 | 说明 |
|---|---|---|
url | 必填 | 音频文件完整 URL |
name | Untitled | 歌名 |
artist | Unknown | 歌手 |
cover | 无 | 封面图 URL |
隐藏式背景音乐
bgm shortcode 用于"页面 BGM"场景:无可见播放器、单曲循环、自动播放(首次交互后触发),右上角一个浮动按钮控制暂停/播放。
建议同时在 frontmatter 里关掉全局播放器,避免两个音源同响:
---
title: "..."
disableGlobalPlayer: true
---
{{< bgm url="https://img.zero9501.online/music/talang.mp3" >}}
参数:
| 参数 | 默认 | 说明 |
|---|---|---|
url | 必填 | 音频文件完整 URL |
volume | 0.5 | 0~1,初始音量 |
position | top-right | 浮动按钮位置:top-right / top-left / bottom-right / bottom-left |
十、地图嵌入(Google Maps)
gmap shortcode 嵌入 Google Maps,不需要 API Key,从官方复制嵌入 URL 即可。
获取嵌入 URL 的步骤:
- 在 Google Maps 打开目标位置
- 点 分享 / Share → 选 嵌入地图 / Embed a map 标签
- 复制 iframe 标签里
src="..."那串完整 URL
{{< gmap src="https://www.google.com/maps/embed?pb=..." >}}
# 自定义高度 + 说明文字
{{< gmap src="..." height="480" caption="东京塔附近" >}}
效果:
参数:
| 参数 | 默认 | 说明 |
|---|---|---|
src | 必填 | Google Maps 嵌入 URL(必须以 https://www.google.com/maps/embed 开头) |
height | 380 | iframe 高度(px) |
caption | 无 | 地图下方说明文字 |
十一、相册轮播(carousel)
carousel shortcode 把多张图变成可左右切换的相册式轮播,适合"组图回顾"、“对比图”、“旅行片段"这类场景。每行一张图,| 后跟可选说明文字。
{{< carousel >}}
https://picsum.photos/id/1015/1600/900 | 峡谷河湾
https://picsum.photos/id/1018/1600/900 | 雪山湖泊
https://picsum.photos/id/1016/1600/900
{{< /carousel >}}
效果(鼠标移上去显示左右箭头,底部短横条指示当前张数;移动端可左右滑动):
带自动播放(每 3 秒切一张)+ 4:3 比例:
{{< carousel ratio="4/3" autoplay="3000" >}}
url1 | caption1
url2 | caption2
{{< /carousel >}}
参数:
| 参数 | 默认 | 说明 |
|---|---|---|
ratio | 16 / 9 | 容器宽高比(如 16/9 / 4/3 / 1/1 / 3/2) |
autoplay | 0 | 自动切换间隔毫秒,0 关闭;常用 3000~5000 |
loop | true | 走到最后一张是否回到第一张;false 时尾页会禁用"下一张"按钮 |
交互:
- 鼠标悬停 显示左右切换按钮,自动播放也会暂停
- 触摸滑动(移动端)拖动 > 40px 触发翻页
- 键盘 容器获取焦点后
←/→切换 - 单图 自动隐藏所有控件,退化成普通大图
十二、视频文件播放(video)
前面的 YouTube / Vimeo 是嵌入第三方平台。如果视频文件就在自己的图床 / R2 / 静态目录里(.mp4 等),用 video shortcode 直接播放——自带一套贴合主题的深色播放器,零依赖、不加载任何外部脚本:
{{< video src="https://cdn.zero9501.online/video/demo.mp4" >}}
效果(默认 16:9 比例,鼠标移上去显示控制条,播放中静止片刻自动隐藏):
带封面图 + 适配非 16:9 视频(下面这段是 12:5 的宽幅片,给 ratio 设成它的真实比例即可不留黑边):
{{< video src="/video/wide.mp4" poster="https://picsum.photos/id/180/1600/900" ratio="12/5" >}}
参数:
| 参数 | 默认 | 说明 |
|---|---|---|
src | 必填 | 视频文件完整 URL 或站内绝对路径 |
poster | 无 | 封面图,未播放时显示 |
ratio | 16 / 9 | 容器宽高比;非 16:9 视频建议设为其真实比例以免黑边,如 4/3 / 1/1 / 12/5 |
loop | false | 是否循环播放 |
muted | false | 是否静音(配合 autoplay 才能自动播放) |
autoplay | false | 是否自动播放(多数浏览器要求同时 muted) |
preload | metadata | 预加载策略:none / metadata / auto |
交互:
- 播放 / 暂停 点画面、中央大按钮,或控制条按钮
- 进度条 点击跳转,按住左右拖拽快速预览
- 音量 鼠标移到喇叭上展开音量条,点图标静音
- 全屏 右下角按钮,或快捷键
F - 键盘 容器获得焦点后:
空格/K播放暂停、←/→快退快进 5 秒、↑/↓调音量、M静音、F全屏 - 控制条 播放中静止约 2.5 秒自动隐藏,移动鼠标重新显示
十三、数据图表(chart)
chart shortcode 在构建期把数据直接画成内联 SVG——不加载任何图表库、不需要 JS,版式参照 anthropic.com 的模型发布页:细框、左上标题、右上副标题、右对齐图例、框外居中说明。线条与文字颜色走主题变量,五种主题自动适配。
折线图
每行一条系列:名称 | 颜色 | 数据点。数据点写成 x:y,可追加点标签 x:y:标签,再加 :b 把标签画在点下方。颜色留空按色板轮换。
{{< chart type="line" title="Terminal-Bench 4.0" subtitle="Accuracy vs Cost"
x="Cost per attempt (USD, log scale)" y="Score (%)"
xscale="log" xmin="1.4" xmax="25" xticks="2,5,10,20"
caption="说明文字,支持 **Markdown**" >}}
Opus 5.5 | clay | 1.5:38.5:low, 3:57.5:med, 4:64.2:high, 7.3:66.5:xhigh, 11:65:max
Fable 5.1 | #2aa876 | 5.8:40.2, 7.8:43.3, 10.5:49.4, 16:51.2, 19.5:55.8
GPT-5.6 Sol | #d1cfc5 | 1.6:8, 2.7:21, 4:26.1, 5.4:28.6, 8:37.3
{{< /chart >}}
效果(鼠标停在点上显示数值,悬停一条折线会淡化其它折线):
横向柱状图
每行一根柱子:标签 | 副标签 | 数值。标签里 **粗体** 的部分加粗,副标签以灰色小字显示在下方,可留空。
{{< chart type="bar" title="Inference speedup" x="Speedup on an NVIDIA H100 (×)"
suffix="×" ref="1" reflabel="Original implementation" xmax="3" >}}
**ChromBPNet** (6M) | 2.1-kb DNA sequence | 1.6
**ProGen2** (6.4B) | 512-amino-acid protein | 2.5
{{< /chart >}}
效果:
多图切换
多张图需要切换时,直接套进第六节的 tabs / tab,标签栏在 claude 主题下会变成官网式的纯文字 Tab:
{{< tabs >}}
{{< tab "Agentic scientific research" >}}
{{< chart ... >}}...{{< /chart >}}
{{< /tab >}}
{{< tab "Agentic terminal coding" >}}
{{< chart ... >}}...{{< /chart >}}
{{< /tab >}}
{{< /tabs >}}
通用参数:
| 参数 | 默认 | 说明 |
|---|---|---|
type | line | 图表类型:line 折线图 / bar 横向柱状图 |
title | 无 | 左上角标题 |
subtitle | 无 | 右上角副标题 |
caption | 无 | 框外居中说明,支持 Markdown |
x / y | 无 | 横轴 / 纵轴标题(柱状图只有 x) |
折线图参数:
| 参数 | 默认 | 说明 |
|---|---|---|
xscale | 线性 | 设为 log 使用对数横轴,刻度自动取 1 / 2 / 5 × 10ⁿ |
xmin / xmax | 按数据 | 横轴范围;对数轴默认两端各留一点余量 |
ymin / ymax | 0 / 按数据 | 纵轴范围,自动取整到整齐刻度 |
xticks | 自动 | 手动指定横轴刻度,如 10,15,20,30 |
柱状图参数:
| 参数 | 默认 | 说明 |
|---|---|---|
color | heather | 柱子颜色 |
suffix | 无 | 数值后缀,如 × / % |
ref / reflabel | 无 | 虚线参考线的位置 / 顶部标签 |
xmax | 按数据 | 横轴上界 |
labelw | 190 | 左侧标签区宽度(SVG 单位),标签很长时调大 |
颜色可以用 Anthropic 官网色板的命名色:clay olive sky fig cactus heather coral oat sage mist cloud slate,也可以直接写 #hex。
十四、基准对比表(bench)
普通 Markdown 表格做不到高亮某一列、单元格加小字注释、行标签跨行合并——bench shortcode 专门处理这类模型评测对比表。
{{< bench highlight="1" color="olive" caption="说明文字" >}}
| Fable 5.1 | Fable 5 | Opus 5
Agentic coding / Terminal-Bench 4.0 | 55.8% ~ 60.9% (Mythos 5.1) | 42.0% | 52.3%
Multidisciplinary reasoning / Humanity's Last Exam | 60.9% ~ no tools | 57.8% ~ no tools | 56.6% ~ no tools
^ | 65.0% ~ with tools | 63.8% ~ with tools | 63.6% ~ with tools
{{< /bench >}}
效果:
| Fable 5.1 | Fable 5 | Opus 5 | GPT-5.6 Sol | |
|---|---|---|---|---|
| Agentic scientific researchTerminal-Bench-Science 0.1 [1] | 52.6% | 24.7% | 29.0% | 22.4% |
| Agentic codingTerminal-Bench 4.0 | 55.8%60.9% (Mythos 5.1) | 42.0% | 52.3% | 37.3% |
| Computer useOSWorld 2.0 [2] | 77.9%partial | 72.9%partial | 75.4%partial | — |
| Multidisciplinary reasoningHumanity’s Last Exam | 60.9%no tools | 57.8%no tools | 56.6%no tools | — |
| 65.0%with tools | 63.8%with tools | 63.6%with tools | — | |
| Agentic codingCursorBench 3.2.0 | 73.4% | 70.5% | 70.0% | 67.2% |
书写约定:
- 表头:以
|开头的一行,首列(行标签列)留空不写 - 行标签:
主标题 / 副标题,主标题加粗,副标题灰色 - 单元格:
数值 ~ 注释,注释以小字显示在数值下方 - 合并:行标签写
^,与上一行合并成一个跨行单元格
参数:
| 参数 | 默认 | 说明 |
|---|---|---|
highlight | 0 | 高亮第几列数据(从 1 开始),0 不高亮 |
color | olive | 高亮色,可用命名色或 #hex |
caption | 无 | 表格下方说明,支持 Markdown |
表格较宽时,移动端可横向滑动查看。