Skip to content

Shortcode 使用

短代码是 Hugo 的强大功能，可让你在 Markdown 文件中嵌入丰富的交互内容。本指南涵盖所有可用短代码的示例和配置选项。

概览

短代码扩展了 Markdown 的动态功能：

  • 媒体嵌入：视频、音频和交互内容
  • UI 组件：提示框、标签页、折叠面板和按钮
  • 数据可视化：图表、流程图和思维导图
  • 内容组织：列表、表格和结构化布局

快速参考

短代码 作用 示例
callout 提示框 {{< callout note "标题" >}}内容{{< /callout >}}
figure 增强图片 {{< figure src="image.jpg" title="标题" >}}
markmap 思维导图 {{< markmap file="map.md" >}}
bilibili 视频嵌入 {{< bilibili bv="BV123" >}}
podcast 音频播放器 {{< podcast episode="123456" >}}
detail 折叠内容 {{< details title="摘要" >}}内容{{< /details >}}
list_children 页面导航 {{< list_children style="cards" >}}
table 增强表格 {{< table title="标题" >}}Markdown 表格{{< /table >}}
cta 行动按钮 {{< cta cta_text="点击" cta_link="/link" >}}
include_code 引入代码文件 {{< include_code file="script.js" >}}

内容增强短代码

Callout（提示框）

创建不同样式的醒目提示框。

基本用法：

{{< callout type="info" >}}
这是一个信息提示框，包含重要内容。
{{< /callout >}}

参数：

参数 类型 可选值 说明
type string info, warning, danger, success, note 提示框样式
title string 任意文本 可选自定义标题
icon string Font Awesome 类名 自定义图标

示例：

{{< callout type="info" title="技巧" >}}
使用快捷键提升工作效率。
{{< /callout >}}

{{< callout type="warning" >}}
此操作不可撤销，请谨慎操作。
{{< /callout >}}

{{< callout type="success" icon="fas fa-check-circle" >}}
配置成功完成！
{{< /callout >}}

Details（折叠面板）

创建可折叠内容区域。

用法：

{{< details title="点击展开高级选项" >}}
此内容默认隐藏，点击后展开。

你可以包含：
- 列表
- 代码块
- 图片
- 其他 Markdown 内容
{{< /details >}}

参数：

参数 类型 说明
title string 折叠面板标题
open boolean 是否默认展开

示例：

{{< details title="高级配置" open="true" >}}
```yaml
advanced_settings:
  cache_timeout: 3600
  max_connections: 100
  debug_mode: false
```
{{< /details >}}

Tabs（标签页）

用标签页组织内容。

用法：

{{< tabs >}}
{{< tab "YAML" >}}
```yaml
apiVersion: v1
kind: Service
metadata:
  name: my-service
```

{{< /tab >}}
{{< tab "JSON" >}}

```json
{
  "apiVersion": "v1",
  "kind": "Service",
  "metadata": {
    "name": "my-service"
  }
}
```

{{< /tab >}}
{{< tab "TOML" >}}

```toml
[metadata]
name = "my-service"
```

{{< /tab >}}
{{< /tabs >}}

功能：

  • 自动切换标签
  • 支持键盘导航
  • 移动端响应式
  • 代码块语法高亮

媒体短代码

Figure（图片）

增强图片展示，支持标题和说明。

用法：

{{< figure src="architecture-diagram.webp"
           title="系统架构"
           caption="微服务架构概览"
           width="800"
           height="600" >}}

参数：

参数 类型 说明
src string 图片路径
title string 图片标题（显示在上方）
caption string 图片说明（显示在下方）
alt string 无障碍文本
width integer 图片宽度
height integer 图片高度
class string CSS 样式类

Bilibili 视频

响应式嵌入 Bilibili 视频。

用法：

{{< bilibili bv="BV1634y1w7Nu" caption="Istio Advisor Plus GPT 演示视频" >}}

参数：

参数 类型 必填 说明
bv string ✅ Bilibili BV 号
aid string ❌ 可选 AV 号
cid string ❌ 可选分集 ID
caption string ❌ 视频描述

示例：

{{< bilibili bv="BV1634y1w7Nu"
             aid="36041724"
             cid="63259487"
             caption="技术演示：如何使用 Istio 解决服务网格问题" >}}

Podcast 播放器

嵌入播客，支持完整播放器功能。

用法：

{{< podcast episode="/zh/podcast/episode-001/" >}}

功能：

  • 播放/暂停控制
  • 进度条与拖动
  • 播放速度调节（0.75x~2x）
  • 时间显示
  • 节目信息
  • 移动端响应式

交互短代码

Markmap（思维导图）

用 Markdown 文件生成交互式思维导图。

用法：

{{< markmap file="mindmap.md" height="600px" >}}

参数：

参数 类型 默认值 说明
file string 必填 Markdown 文件路径
height string 400px 容器高度
width string 100% 容器宽度

思维导图文件格式：

# 中心主题

## 分支 1
- 项目 1
- 项目 2
  - 子项 1
  - 子项 2

## 分支 2
- 项目 A
- 项目 B

## 分支 3
- 项目 X
- 项目 Y

功能：

  • 交互式缩放与拖动
  • 分支可折叠
  • 全屏模式
  • 移动端触控支持
  • 导出功能

Mermaid 图表

用 Mermaid 语法创建各种图表。

流程图：

```mermaid
graph TD
    A[开始] --> B{决策}
    B -->|是 | C[流程 A]
    B -->|否| D[流程B]
    C --> E[结束]
    D --> E
```

时序图：

```mermaid
sequenceDiagram
    participant A as 客户端
    participant B as 服务端
    A->>B: 请求
    B-->>A: 响应
```

类图：

```mermaid
classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +String breed
        +bark()
    }
    Animal <|-- Dog
```

内容组织短代码

List Children（子页面列表）

自动生成子页面列表。

用法：

{{< list_children >}}

参数：

参数 类型 默认值 说明
show_summary boolean true 显示页面描述
show_weight boolean false 显示页面权重
show_date boolean false 显示页面日期
style string list 展示样式（list 或 cards）
limit integer 不限 最大显示页面数
title string 目录 区块标题

示例：

{{< list_children show_summary="true" show_date="true" >}}

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

Table（表格）

增强表格，支持排序和筛选。

用法：

{{< table title="团队成员" >}}
| 姓名 | 职位 | 经验 |
|------|------|------|
| Alice | 开发 | 5 年 |
| Bob | 设计 | 3 年 |
| Carol | 管理 | 8 年 |
{{< /table >}}

功能：

  • 列排序
  • 响应式设计
  • 搜索/筛选
  • 导出选项

代码与技术短代码

Code Block（代码块）

增强代码块，支持更多功能。

用法：

{{< code lang="bash" title="安装脚本" copy="true" >}}
#!/bin/bash
curl -sSL https://get.docker.com/ | sh
sudo usermod -aG docker $USER
{{< /code >}}

参数：

参数 类型 说明
lang string 编程语言
title string 代码块标题
copy boolean 显示复制按钮
line_numbers boolean 显示行号
highlight string 高亮行（如 "2,4-6"）

Terminal（终端）

模拟命令行界面。

用法：

{{< terminal >}}
$ kubectl get pods
NAME                     READY   STATUS    RESTARTS   AGE
nginx-6d4cf56db6-4x8kw   1/1     Running   0          2m
{{< /terminal >}}

布局短代码

Columns（多列布局）

创建多列内容布局。

用法：

{{< columns >}}
{{< column width="60%" >}}
# 主内容
这里是主内容区，空间较大。
{{< /column >}}

{{< column width="40%" >}}
# 侧边栏
这里是侧边栏内容，空间较小。
{{< /column >}}
{{< /columns >}}

Grid（网格布局）

创建响应式网格布局。

用法：

{{< grid cols="3" >}}
{{< grid-item >}}
### 功能 1
功能 1 说明
{{< /grid-item >}}

{{< grid-item >}}
### 功能 2
功能 2 说明
{{< /grid-item >}}

{{< grid-item >}}
### 功能 3
功能 3 说明
{{< /grid-item >}}
{{< /grid >}}

工具类短代码

Button（按钮）

创建带链接的样式化按钮。

用法：

{{< button href="https://example.com" type="primary" size="large" >}}
立即开始
{{< /button >}}

参数：

参数 类型 可选值 说明
href string URL 按钮链接
type string primary, secondary, success, warning, danger 按钮样式
size string small, medium, large 按钮大小
target string _blank, _self 链接打开方式

Badge（徽章）

为内容添加徽章或标签。

用法：

{{< badge type="success" >}}新{{< /badge >}}
{{< badge type="warning" >}}测试版{{< /badge >}}
{{< badge type="info" >}}v2.0{{< /badge >}}

Icon（图标）

插入 Font Awesome 图标。

用法：

{{< icon "fas fa-download" >}} 下载
{{< icon "fab fa-github" >}} GitHub
{{< icon "fas fa-external-link-alt" >}} 外部链接

高级短代码

Chart（图表）

创建交互式图表和统计图。

用法：

{{< chart type="line" data="chart-data.json" height="400px" >}}

支持图表类型：

  • 折线图
  • 柱状图
  • 饼图
  • 散点图
  • 面积图

Map（地图）

嵌入交互式地图。

用法：

{{< map lat="39.9042" lng="116.4074" zoom="10" >}}

Timeline（时间轴）

创建可视化时间轴。

用法：

{{< timeline >}}
{{< timeline-item date="2020-01" title="项目启动" >}}
项目初始化与规划阶段。
{{< /timeline-item >}}

{{< timeline-item date="2020-06" title="Beta 发布" >}}
首个 Beta 版本发布给部分用户。
{{< /timeline-item >}}

{{< timeline-item date="2021-01" title="正式上线" >}}
正式发布，功能全面。
{{< /timeline-item >}}
{{< /timeline >}}

自定义

自定义 CSS

为短代码添加自定义样式：

// 自定义 callout 样式
.callout.callout-custom {
  border-left: 4px solid #ff6b6b;
  background: #fff5f5;

  .callout-title {
    color: #ff6b6b;
  }
}

自定义短代码

在 layouts/shortcodes/ 目录下添加文件即可创建自定义短代码：

<!-- layouts/shortcodes/custom-alert.html -->
<div class="alert alert-{{ .Get "type" | default "info" }}">
  {{ if .Get "title" }}
    <h4>{{ .Get "title" }}</h4>
  {{ end }}
  {{ .Inner | markdownify }}
</div>

用法：

{{< custom-alert type="warning" title="重要" >}}
这是一个自定义警告短代码。
{{< /custom-alert >}}

最佳实践

性能

  1. 优化媒体：使用合适的文件大小和格式
  2. 懒加载：为图片和视频启用懒加载
  3. 缓存：利用浏览器缓存静态资源

可访问性

  1. Alt 文本：图片务必提供 alt 属性
  2. 键盘导航：确保交互元素可用键盘操作
  3. 屏幕阅读器：使用语义化 HTML 和 ARIA 标签

SEO

  1. 结构化数据：使用合适的 schema 标记
  2. 图片优化：包含描述性文件名和 alt 文本
  3. 内容层级：合理使用标题结构

故障排查

常见问题

短代码未渲染

问题：短代码显示为普通文本

解决方法：

  1. 检查短代码语法和拼写
  2. 确认 layouts/shortcodes/ 下有对应文件
  3. 校验参数名称和值
  4. 检查短代码标签是否闭合

样式异常

问题：短代码样式不正确

解决方法：

  1. 检查 CSS 文件是否加载
  2. 校验 CSS 类名
  3. 检查是否有样式冲突
  4. 在不同设备/浏览器测试

JavaScript 错误

问题：交互短代码无法正常工作

解决方法：

  1. 查看浏览器控制台错误
  2. 检查所需 JS 库是否加载
  3. 校验脚本执行顺序
  4. 确认浏览器已启用 JS

后续步骤

掌握短代码后可：

相关主题

需要帮助？请查阅 故障排查指南 或 贡献指南。