Hextra 主题 Shortcodes 速查：让你的 Hugo 博客更生动
Hextra 是一个基于 Hugo 的现代化文档/博客主题，除了标准 Markdown 语法外，还提供了丰富的 Shortcodes 来增强内容表现力。本文整理了最常用的 Shortcodes，每个都附带写法和真实渲染效果，方便日常写作时快速查阅。
折叠内容 (details)
用于隐藏/展示一段内容，适合 FAQ、补充说明等场景。
默认展开
点击折叠
代码、链接、列表等。
{{% details title="点击折叠" %}}
这是一段默认展开的内容，支持 **Markdown** 格式。
{{% /details %}}默认折叠
点击展开查看
{{% details title="点击展开查看" closed="true" %}}
这是一段默认折叠的内容。
{{% /details %}}Note
必须使用 {{% %}} 分隔符（百分号），否则内部 Markdown 不会被渲染。
提示框 (callout)
用于在正文中插入醒目的提示信息。
默认（橙色）
{{< callout >}}
这是一个默认样式的提示框。
{{< /callout >}}信息（蓝色）
{{< callout type="info" >}}
这是一个信息提示框，用于补充说明。
{{< /callout >}}警告（黄色）
{{< callout type="warning" >}}
这是一个警告提示框，请注意。
{{< /callout >}}错误（红色）
{{< callout type="error" >}}
这是一个错误提示框，危险操作。
{{< /callout >}}自定义 emoji
{{< callout emoji="👾" >}}
可以用任意 emoji 作为图标。
{{< /callout >}}GitHub 风格 Alerts
和 callout 类似，但语法更轻量，不需要 shortcode 标签。
Note
补充说明信息（蓝色）。
Tip
有用的建议（绿色）。
Important
重要信息（紫色）。
Warning
需要注意（琥珀色）。
Caution
危险操作（红色）。
> [!NOTE]
> 补充说明信息（蓝色）。
> [!TIP]
> 有用的建议（绿色）。选择建议： 需要自定义 emoji → 用 callout；简单标注 → 用 Alerts。
标签页 (tabs)
用于并列展示多组内容，如多语言代码对比、多平台安装步骤。
{ "hello": "world" }hello: worldhello = "world"{{< tabs items="JSON,YAML,TOML" >}}
{{< tab >}}
```json
{ "hello": "world" }
```
{{< /tab >}}
{{< tab >}}
```yaml
hello: world
```
{{< /tab >}}
{{< tab >}}
```toml
hello = "world"
```
{{< /tab >}}
{{< /tabs >}}默认选中第一个标签，可通过 defaultIndex="1" 改为默认选中第二个。
卡片网格 (cards + card)
用于展示文章推荐、资源列表等，支持图标、图片和标签。
{{< cards cols="2" >}}
{{< card link="/blog" title="访问博客" icon="pencil" subtitle="查看所有文章" >}}
{{< card link="/about" title="关于我" icon="user" subtitle="了解更多" >}}
{{< /cards >}}带标签的卡片：
{{< card link="/blog" title="带标签" tag="新" tagType="info" >}}
{{< card link="/blog" title="警告标签" tag="注意" tagType="warning" >}}步骤流程 (steps)
用于展示教程、操作指南等按步骤排列的内容。
第一步
安装 Hugo：brew install hugo（macOS）或 choco install hugo（Windows）。
第二步
创建站点：hugo new site myblog
第三步
选择主题并部署上线。
{{% steps %}}
### 第一步
安装 Hugo：`brew install hugo`（macOS）或 `choco install hugo`（Windows）。
### 第二步
创建站点：`hugo new site myblog`
### 第三步
选择主题并部署上线。
{{% /steps %}}Note
每一步必须是 ###（H3）标题。使用 {{% %}} 分隔符。
代码块增强
在代码块的语言标记后加 {filename="文件名"} 可显示文件名标签。
def hello():
print("Hello, world!")```python {filename="app.py"}
def hello():
print("Hello, world!")
```Mermaid 图表
直接在代码块中写 Mermaid 语法即可渲染为 SVG 图表。
graph LR
A[开始] --> B[处理]
B --> C[结束]```mermaid
graph LR
A[开始] --> B[处理]
B --> C[结束]
```文件树 (filetree)
用于展示目录结构，文件夹可展开/折叠。
- _index.md
-
- post1.md
- post2.md
{{< filetree/container >}}
{{< filetree/folder name="content" state="open" >}}
{{< filetree/file name="_index.md" >}}
{{< filetree/folder name="blog" state="open" >}}
{{< filetree/file name="post1.md" >}}
{{< /filetree/folder >}}
{{< /filetree/folder >}}
{{< /filetree/container >}}state 参数："open"（默认展开）或 "closed"（默认折叠）。
行内徽章 (badge)
用于行内小标签，支持 4 种颜色。
默认：
{{< badge content="默认" >}}
{{< badge content="信息" type="info" >}}
{{< badge content="警告" type="warning" >}}
{{< badge content="错误" type="error" >}}带链接和图标：
{{< badge content="GitHub" link="https://github.com" icon="github" >}}行内图标 (icon)
在文字中插入 Heroicons 图标。
GitHub、 学术、 编辑
{{< icon "github" >}} GitHub、{{< icon "academic-cap" >}} 学术Note
需在站点配置中启用 enableInlineShortcodes: true。
PDF 嵌入
以 iframe 形式嵌入 PDF 阅读器。
{{< pdf "path/to/file.pdf" >}}支持远程 URL 和本地文件路径（放在 page bundle 中）。
Jupyter Notebook
直接渲染 .ipynb 文件，支持代码单元格（带语法高亮）、Markdown 单元格和图片输出。
{{% jupyter "notebook.ipynb" %}}使用 {{% %}} 分隔符，支持远程 URL。
快速对照表
| 需求 | Shortcode | 分隔符 |
|---|---|---|
| 可折叠文本 | details |
{{% %}} |
| 提示框 | callout |
{{< >}} |
| 标签页 | tabs + tab |
{{< >}} |
| 步骤流程 | steps |
{{% %}} |
| 卡片网格 | cards + card |
{{< >}} |
| 文件目录树 | filetree/* |
{{< >}} |
| 嵌入 PDF | pdf |
{{< >}} |
| 嵌入 Notebook | jupyter |
{{% %}} |
| 行内图标 | icon |
{{< >}} |
| 徽章标签 | badge |
{{< >}} |
| 流程图/图表 | Mermaid | ```mermaid |
| 带文件名代码 | 代码块属性 | ```lang {filename="..."} |
完整参数文档可参考 Hextra 官方 Shortcodes 文档。