总览

本站基于 Hugo，在 layouts/shortcodes/ 下提供了 15 个自定义 Shortcode。本文是权威参考；复杂组件（B 站、YouTube、思维导图、问答、子页面列表、Marp 幻灯片）另有单独详解页。

通用规则

位置参数用 {{< sc "0" >}}（如 callout），命名参数用 key="value"。
含正文的组件用闭合形式：{{</* sc */>}}...{{</* /sc */>}}。
Shortcode 不能嵌套同名；表格类用 {{< table >}} 自动生成「表 N」编号。

内容与版式¶

callout — 提示框¶

彩色提示框（note / tip / warning）。

{{</* callout tip "为什么这个框架有价值" */>}}
正文，支持 **Markdown**。
{{</* /callout */>}}

参数	说明
`0`（位置）	类型：`note` / `tip` / `warning`
`1`（位置）	标题（可选）
正文	提示内容

details — 折叠块¶

可折叠区域。

{{</* details title="点击展开" open="true" */>}}
折叠内容。
{{</* /details */>}}

参数：title、open（默认折叠）。

figure — 图片¶

带标题/链接/尺寸的图片，支持页面资源自动取宽高。

{{</* figure src="diagram.svg" title="图示说明" width="80%" */>}}

主要参数：src、title、caption、link、target、rel、width、height、id、attr、attrlink。

SVG 注意

figure 对本地 SVG 资源会调用 .Width，对矢量图会报错。嵌入本地 SVG 请用 Markdown 图片语法 ![alt](file.svg)；外部 SVG 不受影响。

table — 带标题表格¶

把 Markdown 表格包进 table，自动生成「表 N：标题」编号。

{{</* table title="传统 AI 与 Agentic AI 对照" */>}}
| 特性 | 传统 AI | Agentic AI |
| ---- | ------- | ---------- |
| 状态 | 无状态  | 有状态     |
{{</* /table */>}}

参数：title（编号标题，可选）。

cta — 行动号召按钮¶

在页面底部渲染主/次按钮。

{{</* cta cta_text="开始使用" cta_link="/docs/" cta_new_tab="true" cta_alt_text="GitHub" cta_alt_link="https://github.com/rootsongjc/website" */>}}

section-toc — 子页面列表¶

列出当前 section 下的子页面。详见子页面列表详解。

{{</* section-toc title="本章节" limit="10" show_summary="true" show_date="true" */>}}

参数：title、limit、show_summary、show_date、show_weight、style。

媒体嵌入¶

bilibili — B 站视频¶

详见 B 站视频详解。

{{</* bilibili bv="BV1xx..." caption="视频标题" */>}}

参数：bv（或 aid）、cid、caption。

youtube — YouTube 视频¶

详见 YouTube 详解。

{{</* youtube id="dQw4w9WgXcQ" */>}}

参数：id（视频 ID）。

podcast — 播客单集¶

内联播客播放条（中文站 content/zh/podcast/）。

{{</* podcast episode="episode-1" show="my-show" height="160" */>}}

参数：episode、show、height。

whimsical — Whimsical 嵌入¶

{{</* whimsical url="https://whimsical.com/..." */>}}

markmap — 思维导图¶

从 Markdown 文件渲染思维导图，支持全屏。详见思维导图全屏。

{{</* markmap file="markmaps/my-map.md" height="500" title="架构图" */>}}

参数：file、height、title。

marp-slide — 本地 Marp 幻灯片¶

嵌入本地 Marp 生成的幻灯片。详见 Marp 幻灯片详解。

{{</* marp-slide src="slides/intro.html" height="480" title="入门" */>}}

参数：src、height、style、title。

online-slide — 在线幻灯片¶

嵌入外部在线幻灯片 URL。

{{</* online-slide url="https://slides.com/..." title="分享" */>}}

参数：url、title。

代码与交互¶

inline-codes — 代码注解¶

在代码块上叠加高亮区间与标签（用于逐行讲解）。参数：file、lang、ranges、labels、labelRanges、lineStart、lineEnd、lineLabels、highlight、title。

{{</* inline-codes file="main.py" lang="python" ranges="1-3" labels="1:入口" */>}}

quiz — 问答系统¶

从 dataset 渲染选择题/问答题。详见问答系统详解。

{{</* quiz dataset="quizzes/chapter1.json" */>}}

参数：dataset（题目数据文件）。

索引速查¶

Shortcode	用途	详解页
`callout`	提示框	—
`details`	折叠块	—
`figure`	图片	—
`table`	带标题表格	—
`cta`	行动按钮	—
`section-toc`	子页面列表	✓
`bilibili`	B 站视频	✓
`youtube`	YouTube	✓
`podcast`	播客单集	—
`whimsical`	Whimsical	—
`markmap`	思维导图	✓
`marp-slide`	Marp 幻灯片	✓
`online-slide`	在线幻灯片	—
`inline-codes`	代码注解	—
`quiz`	问答系统	✓