跳至内容

Markdown 数据驱动短代码

Markdown 数据驱动短代码

背景与动机

在内容丰富的技术站点中,经常需要重复使用相同的 UI 片段——比如警告框、选项卡、代码块演示等。传统的做法是直接在 Markdown 中编写重复的 HTML 或短代码调用,这不仅增加了维护成本,还使内容与展示紧耦合。通过将展示数据(如标题、颜色、图标)存放在独立的 JSON 或 YAML 文件中,短代码只负责读取数据并渲染模板,可以实现:

  • 内容编辑者无需了解 HTML/CSS 即可修改展示效果
  • 样式统一,全局修改只需更新数据文件
  • 可复用性提升,同一套短代码可在多个页面中使用不同数据

核心概念

数据文件结构

将数据放置在 data/ 目录下,以 YAML 为例:

# data/alerts.yml
- id: warning
  title: "警告"
  icon: "⚠️"
  color: "#ff9800"
  bg: "#fff3e0"
- id: tip
  title: "提示"
  icon: "💡"
  color: "#4caf50"
  bg: "#e8f5e9"

Shortcode 实现

在 layouts/shortcodes/alert.html 中:

{{ $data := .Site.Data.alerts }}
{{ $item := (index $data (isset .Params "type" | ternary .Params.Type "info")) }}
<div class="alert alert-{{ .Params.type | default "info" }}" style="border-left: 4px solid {{ .Item.color }}; background-color: {{ .Item.bg }};">
  <div class="alert-header">
    <span class="alert-icon">{{ .Item.icon }}</span>
    <strong>{{ .Item.title }}</strong>
  </div>
  <div class="alert-body">
    {{ .Inner | markdownify }}
  </div>
</div>

使用方式

在任意 Markdown 文件中:


这是一个警告消息,内容将被安全地转换为 Markdown。

实施步骤

  1. 准备数据文件:在 data/ 目录下创建所需的 YAML/JSON 文件,确保结构统一。
  2. 编写短代码模板:在 layouts/shortcodes/ 下创建对应的 HTML 模板,使用 .Site.Data 读取数据。
  3. 添加样式(可选):在 assets/css/custom.css 中定义通用的 .alert 类,或直接在模板内嵌入内联样式。
  4. 在内容中引用:使用
    内容
    调用,将需要展示的内容放在标签内部。
  5. 测试与调整:本地运行 hugo server 查看效果,根据实际显示调整数据字段或模板。

最佳实践

  • 保持数据粒度细:只存放展示所需的字段,避免冗余。
  • 统一命名约定:在数据文件中用 id、title、icon 这类稳定字段名,便于模板复用。
  • 版本控制:数据文件同样需要进行 Git 管理,便于追溯更改历史。
  • 性能考量:数据文件在 Hugo 站点构建时会被读取,建议保持较小体积,避免影响构建速度。

常见问题 (FAQ)

Q1: 如果我想在同一页面使用多种不同的警告类型,应该怎么做?
A: 只需在每次调用短代码时传入不同的 type 参数,短代码会根据 type 从数据文件中查找对应条目。

Q2: 数据文件支持 JSON 还是 YAML?
A: Hugo 同时支持 .json, .yaml, .yml 格式,你可以根据团队习惯选择任意一种。

Q3: 如何让非技术人员也能维护数据文件?
A: 提供一个简单的编辑界面(比如 Netlify CMS 或 Forestry)并将其指向 data/ 目录,使得业务人员可以通过表单修改数据而无需触碰代码。

参考资料