Skip to content

Shortcode 参考

本文档为网站项目中所有可用的 Hugo Shortcode 提供详细参考。

内容 Shortcode

callout

用于创建样式化的提示框，以突出显示重要信息。

语法：

{{< callout type "可选标题" >}}
内容在此处
{{< /callout >}}

参数说明：

  • type（必填）：提示类型 - note、tip、warning
  • title（可选）：自定义提示标题

示例：

{{< callout note "重要信息" >}}
这是带自定义标题的 note 类型提示框。
{{< /callout >}}

{{< callout tip >}}
这是没有自定义标题的 tip 类型提示框。
{{< /callout >}}

{{< callout warning "注意" >}}
这是 warning 类型提示框。
{{< /callout >}}

输出效果：

  • 生成带有相应颜色和图标的样式化容器
  • 支持在提示框内使用 markdown 内容
  • 自动处理 emoji 表情

detail

创建可折叠内容区域（HTML <details> 元素）。

语法：

{{< details title="摘要文本" >}}
隐藏内容在此处
{{< /details >}}

参数说明：

  • summary（必填）：显示在折叠区域的摘要文本

示例：

{{< details title="点击展开" >}}
此内容默认隐藏，点击摘要可展开。

- 可包含列表
- **加粗文本**
- 以及其他 markdown 内容
{{< /details >}}

输出效果：

  • 生成带唯一 ID 的可折叠区域
  • 支持完整 markdown 内容
  • 自动生成剧透风格样式

figure

增强型图片展示，支持标题和高级功能。

语法：

{{< figure src="image.jpg" title="图片标题" caption="图片说明" >}}

参数说明：

  • src（必填）：图片路径
  • title（可选）：图片标题及 alt 文本
  • caption（可选）：图片说明
  • link（可选）：图片链接地址
  • target（可选）：链接打开方式（如 _blank）
  • rel（可选）：链接关系
  • width（可选）：图片宽度
  • height（可选）：图片高度
  • id（可选）：自定义元素 ID
  • attr（可选）：版权说明
  • attrlink（可选）：版权链接

示例：

{{< figure src="/images/example.jpg" title="示例图片" caption="这是一个示例图片" >}}

{{< figure src="/images/linked.jpg" link="https://example.com" target="_blank" >}}

{{< figure src="/images/sized.jpg" width="500" height="300" >}}

功能特点：

  • 自动懒加载
  • 错误处理与回退
  • 响应式图片尺寸
  • 集成 Hugo 图片处理
  • 本地图片自动检测宽高
  • 支持外部图片链接

table

增强型表格展示，支持标题说明。

语法：

{{< table title="表格标题" >}}
| 表头 1 | 表头 2 |
|-------|-------|
| 单元格 1 | 单元格 2 |
{{< /table >}}

参数说明：

  • caption（可选）：表格说明文字

示例：

{{< table title="月度统计" >}}
| 月份 | 访客数 | 文章数 |
|------|--------|--------|
| 一月 | 1,200  | 5      |
| 二月 | 1,500  | 7      |
| 三月 | 1,800  | 6      |
{{< /table >}}

输出效果：

  • 渲染带样式的 markdown 表格
  • 在表格下方居中显示说明
  • 支持说明中的 emoji

媒体 Shortcode

bilibili

嵌入 Bilibili 视频，支持响应式设计。

语法：

{{< bilibili bv="BV1234567890" caption="视频说明" >}}

参数说明：

  • bv（必填）：Bilibili 视频 BV 号
  • aid（可选）：备用视频 AID
  • cid（可选）：指定视频 CID
  • caption（可选）：视频说明

示例：

{{< bilibili bv="BV1GJ411x7h7" >}}

{{< bilibili bv="BV1GJ411x7h7" caption="Kubernetes 教程视频" >}}

{{< bilibili bv="BV1GJ411x7h7" aid="12345" cid="67890" >}}

功能特点：

  • 响应式 iframe 容器
  • 自动保持宽高比
  • 支持视频说明
  • 安全 iframe 权限限制

podcast

嵌入 Apple Podcasts 节目。

语法：

{{< podcast episode="1000123456789" height="175" >}}

参数说明：

  • episode（必填）：Apple Podcasts 节目 ID
  • show（可选）：播客节目 ID（默认取站点参数）
  • height（可选）：播放器高度（默认 175）

示例：

{{< podcast episode="1000123456789" >}}

{{< podcast episode="1000123456789" height="200" >}}

{{< podcast episode="1000123456789" show="987654321" >}}

功能特点：

  • 安全的 iframe 嵌入
  • 可自定义播放器高度
  • 自动获取节目 ID
  • 支持加密媒体与剪贴板访问

responsive_video

为多种视频源创建响应式视频容器。

语法：

{{< responsive_video src="video.mp4" >}}

参数说明：

  • src（必填）：视频源地址
  • 支持其他 HTML5 视频属性

功能特点：

  • 响应式视频容器
  • HTML5 视频标签
  • 跨浏览器兼容

交互 Shortcode

markmap

根据 markdown 文件创建交互式思维导图，支持高级功能和自定义。

语法：

{{< markmap file="mindmap.md" title="我的思维导图" height="600px" >}}

参数说明：

  • file（必填）：包含思维导图内容的 markdown 文件（相对页面目录）
  • title（可选）：导图标题，显示在折叠摘要
  • height（可选）：容器高度（默认 600px）

思维导图文件格式：

引用的 markdown 文件需包含层级结构，可选前置配置：

---
markmap:
  initialExpandLevel: 2
  colorFreezeLevel: 3
  duration: 500
---

# 中心主题

## 主分支 1

### 子主题 1.1
- 细节 A
- 细节 B
  - 嵌套细节 1
  - 嵌套细节 2

### 子主题 1.2
- 重要说明
- **加粗强调**
- *斜体文本*

## 主分支 2

### 技术概念
- API 设计
- 数据库结构
- 认证流程

### 实施步骤
1. 环境搭建
2. 配置依赖
3. 编写核心逻辑
4. 添加测试
5. 部署上线

## 资源与链接

### 文档
- [官方文档](https://example.com/docs)
- [API 参考](https://example.com/api)

### 工具
- 开发工具
- 测试框架
- 部署平台

前置配置选项：

  • initialExpandLevel：初始展开层级（默认 2）
  • colorFreezeLevel：颜色冻结层级（可选）
  • duration：动画时长（默认 500 毫秒）
  • maxWidth：最大节点宽度（可选）
  • spacingVertical：节点垂直间距（可选）
  • spacingHorizontal：节点水平间距（可选）

高级示例：

基础思维导图：

{{< markmap file="project-overview.md" >}}

自定义思维导图：

{{< markmap file="architecture.md" title="系统架构" height="800px" >}}

复杂配置思维导图： 创建 complex-mindmap.md：

---
markmap:
  initialExpandLevel: 3
  colorFreezeLevel: 2
  duration: 800
---

# 软件开发生命周期

## 规划阶段
### 需求收集
- 利益相关者访谈
- 用户故事编写
- 验收标准定义

### 项目规划
- 时间估算
- 资源分配
- 风险评估

## 开发阶段
### 前端开发
- UI/UX 设计
- 组件开发
- 状态管理

### 后端开发
- API 设计
- 数据库结构
- 业务逻辑

## 测试阶段
### 单元测试
- 组件测试
- 服务测试
- 工具测试

### 集成测试
- API 测试
- 数据库测试
- 端到端测试

## 部署阶段
### CI/CD 流程
- 构建自动化
- 测试自动化
- 部署自动化

### 监控
- 性能监控
- 错误追踪
- 用户分析

功能特点：

  • 交互导航：支持缩放、拖动浏览大型导图
  • 可折叠节点：点击展开/收起分支
  • 全屏模式：支持 ESC 键退出
  • 移动端优化：触控友好，工具栏适配
  • 主题支持：自动适应深色/浅色模式
  • 错误处理：优雅的错误提示与加载状态
  • 性能优化：懒加载与高效渲染
  • 无障碍支持：键盘导航与屏幕阅读器兼容

工具栏功能：

  • 缩放：放大/缩小视图
  • 适应屏幕：自动调整至容器
  • 全部收起：收起所有节点
  • 全屏切换：进入/退出全屏
  • 重置视图：恢复初始状态

移动端特色：

  • 工具栏仅显示核心按钮
  • 支持触控缩放与拖动
  • 响应式容器尺寸
  • 按钮间距优化

故障排查：

  • 确认 markdown 文件与页面同目录
  • 检查 markdown 层级结构与语法
  • 校验前置 YAML 配置
  • 使用浏览器开发者工具查看 JS 错误

mindmap

思维导图的另一种实现（旧版）。

语法：

{{< mindmap file="mindmap.md" >}}

注意： 推荐新项目使用 markmap。

导航 Shortcode

list_children

生成子页面列表或卡片网格。

语法：

{{< list_children title="章节内容" style="cards" show_summary="true" >}}

参数说明：

  • title（可选）：区块标题（默认 "章节目录"）
  • style（可选）：显示样式 - list（默认）或 cards
  • show_summary（可选）：显示页面摘要（默认 true）
  • show_weight（可选）：显示页面权重（默认 false）
  • show_date（可选）：显示页面日期（默认 false）
  • limit（可选）：最多显示页面数量

示例：

{{< list_children >}}

{{< list_children title="相关文章" style="cards" >}}

{{< list_children show_weight="true" show_date="true" limit="5" >}}

{{< list_children style="list" show_summary="false" >}}

样式说明：

列表样式（默认）：

  • 简单无序列表
  • 可选权重与日期
  • 紧凑展示

卡片样式：

  • 网格卡片布局
  • 更丰富的视觉效果
  • 适合展示精选内容

功能特点：

  • 自动页面排序
  • 响应式设计
  • 支持页面描述与摘要
  • 无子页面时显示提示

工具类 Shortcode

slide

嵌入演示幻灯片，响应式 iframe 容器。

语法：

{{< slide src="presentation.html" >}}

参数说明：

  • src（必填）：幻灯片地址（自动添加 ?embed 参数）

示例：

嵌入在线演示：

{{< slide src="https://slides.com/username/presentation" >}}

嵌入本地演示：

{{< slide src="/slides/my-presentation.html" >}}

嵌入 Google Slides：

{{< slide src="https://docs.google.com/presentation/d/1ABC123/embed" >}}

功能特点：

  • 响应式设计：16:9 宽高比自适应
  • 全屏支持：可全屏查看演示
  • 懒加载：仅在需要时加载 iframe
  • 嵌入模式：自动添加 ?embed 参数，简洁展示
  • 多平台兼容：支持多种演示平台
  • 美观容器：圆角与阴影效果

支持平台：

  • Google Slides
  • Slides.com
  • Speaker Deck
  • SlideShare
  • 自定义 HTML 演示
  • PDF 演示（需合适查看器）

样式说明：

  • 16:9 宽高比（56.25% padding-top）
  • 圆角（8px）
  • 阴影效果
  • 宽度自适应（100%）
  • 底部间距

include_code

引用外部代码文件，自动语法高亮并提供下载链接。

语法：

{{< include_code file="example.js" >}}

参数说明：

  • file（必填）：代码文件路径（相对页面目录）

支持文件类型：

  • .html → HTML 标记
  • .js → JavaScript
  • .py → Python
  • .go → Go
  • .sh → Bash/Shell
  • .yaml、.yml → YAML
  • 其他扩展名按原样高亮

示例：

引用 JavaScript 文件：

{{< include_code file="scripts/api-client.js" >}}

引用 Python 脚本：

{{< include_code file="examples/data-processor.py" >}}

引用配置文件：

{{< include_code file="config/docker-compose.yml" >}}

引用 Shell 脚本：

{{< include_code file="scripts/deploy.sh" >}}

功能特点：

  • 自动语言识别：根据扩展名自动高亮
  • 下载链接：可下载引用文件
  • 实时内容：始终显示最新文件内容
  • 语法高亮：完整 Hugo 高亮支持
  • 相对路径：文件路径相对当前页面
  • 错误处理：缺失文件时优雅提示

文件组织示例：

content/
├── blog/
│   ├── my-post/
│   │   ├── index.md
│   │   ├── example.js
│   │   └── config.yml
│   └── another-post/
│       ├── index.md
│       └── scripts/
│           └── deploy.sh

在 my-post/index.md 中：

{{< include_code file="example.js" >}}
{{< include_code file="config.yml" >}}

在 another-post/index.md 中：

{{< include_code file="scripts/deploy.sh" >}}

创建简易图片画廊，支持缩略图点击查看大图。

语法：

{{< gallery link="image.jpg" title="图片说明" >}}

参数说明：

  • link（必填）：图片地址或路径
  • title（必填）：图片标题及 alt 文本

示例：

单个画廊项：

{{< gallery link="/images/architecture.jpg" title="系统架构图" >}}

多个画廊项：

{{< gallery link="/images/frontend.jpg" title="前端界面" >}}
{{< gallery link="/images/backend.jpg" title="后台管理" >}}
{{< gallery link="/images/mobile.jpg" title="移动应用" >}}

外部图片：

{{< gallery link="https://example.com/image.jpg" title="外部图片" >}}

功能特点：

  • 可点击缩略图：点击图片查看大图
  • 居中说明：标题显示在图片下方
  • 响应式设计：图片自适应屏幕
  • 简洁布局：画廊展示简洁美观
  • 无障碍支持：alt/title 属性完善

输出结构： 每个画廊项生成：

  • 图片外层为链接
  • 图片元素带 alt 文本
  • 图片下方居中斜体说明

使用建议：

  • 图片尺寸统一，视觉更美观
  • 标题描述清晰，提升无障碍
  • 图片优化，提升加载性能
  • 可与其他 Shortcode 组合使用

cta

创建主次按钮组，支持多种操作。

语法：

{{< cta cta_text="主操作" cta_link="https://example.com" cta_alt_text="次操作" cta_alt_link="/docs" >}}

参数说明：

  • cta_text（可选）：主按钮文本
  • cta_link（可选）：主按钮链接
  • cta_new_tab（可选）：主按钮新窗口打开（"true"/"false"）
  • cta_alt_text（可选）：次按钮文本
  • cta_alt_link（可选）：次按钮链接
  • cta_alt_new_tab（可选）：次按钮新窗口打开（"true"/"false"）

示例：

单主按钮：

{{< cta cta_text="快速开始" cta_link="/getting-started" >}}

主按钮新窗口：

{{< cta cta_text="立即下载" cta_link="https://github.com/user/repo/releases" cta_new_tab="true" >}}

主次按钮组：

{{< cta cta_text="免费试用"
         cta_link="https://app.example.com/signup"
         cta_new_tab="true"
         cta_alt_text="了解更多"
         cta_alt_link="/features" >}}

仅次按钮：

{{< cta cta_alt_text="查看文档" cta_alt_link="/docs" >}}

功能特点：

  • 主按钮采用 Bootstrap 样式（btn btn-sm btn-primary）
  • 次按钮带箭头图标
  • 按钮文本支持 markdown 和 emoji
  • 可配置新窗口打开
  • 响应式设计
  • 外链安全（rel="noopener"）

Shortcode 最佳实践

性能

  1. 图片优化：优先使用 figure Shortcode 自动优化图片
  2. 懒加载：figure 图片自动懒加载
  3. 响应式设计：所有 Shortcode 均支持移动端

无障碍

  1. Alt 文本：图片务必填写 title 或 caption
  2. 语义 HTML：Shortcode 生成语义化结构
  3. 键盘导航：交互元素支持键盘操作

内容组织

  1. 统一样式：提示类内容统一用 callout
  2. 层级内容：渐进披露用 detail
  3. 媒体集成：不同内容类型用对应 Shortcode

错误处理

  1. 必填参数：务必填写必需参数
  2. 文件路径：确保引用文件存在
  3. 回退内容：Shortcode 内置错误提示与回退

故障排查

常见问题

Shortcode 未渲染：

  • 检查参数语法与拼写
  • 必填参数是否填写
  • 文件型 Shortcode 路径是否正确

图片不显示：

  • 检查图片路径
  • 图片是否存在于指定目录
  • 图片权限是否正确

思维导图不加载：

  • markdown 文件是否与页面同目录
  • markdown 层级结构与语法是否正确
  • 前置配置是否规范

视频无法嵌入：

  • 视频 ID 与参数是否正确
  • 外部视频源是否可访问
  • iframe 安全设置是否合理

调试模式

启用 Hugo 调试模式查看详细 Shortcode 处理信息：

hugo server --debug --verbose

更多示例与高级用法请参见 用户指南 或 故障排查指南。