适用场景

适合在 Hugo 中维护书单、影单、友链、项目列表等重复卡片内容的页面。只要内容条目字段相对固定、数量会持续增加，就可以考虑用 Data Files 替代一条条手写 Shortcode。

背景

网站上有一个阅览页面，用来记录我看过的书和电影。之前为了显示效果，自定义了一个叫 mediacard 的 Shortcode，可以在页面上生成卡片。

在 Markdown 文件里，每条记录都是一次 Shortcode 调用，像这样：

1
2
3
4
5
6

{{< mediacard title="大唐双龙传" 
    coverurl="..." link="..." 
    author="黄易" type="24-01" 
    starscore="★★★" greystar="☆☆" 
    intro="..." 
>}}

刚开始记录不多的时候，这个方法还行。但后来东西越来越多，整个 Markdown 文件就变得特别长，每次想加一条新记录，都要在文件里找很久，维护起来很麻烦。

核心步骤

解决方法

主要思路就是把数据和页面分开。

Hugo 本身提供了 Data Files 功能，允许在 /data 目录下存放 YAML、JSON 或 TOML 格式的数据文件。这样，Markdown 文件就只负责页面结构和展示逻辑，而具体的书影条目数据，则统一放到数据文件里，方便管理。

具体步骤

1. 把数据转移到 data 文件夹

第一步是把之前写在 Markdown 文件里的所有条目数据，都整理出来，放到 /data 文件夹下，这种脏活累活当然是交给 AI 来完成啦！

我新建了 books.yaml 和 movies.yaml 两个文件。

修改前 (在 .md 文件里):

1

{{< mediacard title="法师故事" coverurl="..." author="索斯" type="24-08" ... >}}

修改后 (在 data/books.yaml 文件里):

1
2
3
4
5
6
7
8

- title: "法师故事"
  coverurl: "[https://bookcover.yuewen.com/qdbimg/349573/57821/600.webp](https://bookcover.yuewen.com/qdbimg/349573/57821/600.webp)"
  link: "[https://www.qidian.com/book/57821/](https://www.qidian.com/book/57821/)"
  author: "索斯"
  type: "24-08"
  starscore: "★★★★"
  greystar: "☆"
  intro: "魔兽践踏，巨龙咆哮，巫师诅咒，魔法璀璨之光照耀知识灯塔！"

这样一来，所有的数据都集中管理了，之后增删改查也只用编辑这两个 .yaml 文件就行。

2. 写一个新的 Shortcode

因为数据存放的位置变了，所以需要一个新的 Shortcode 来读取这些数据并显示出来。

我在 layouts/shortcodes/ 目录下新建了一个 medialist.html 文件。这个 Shortcode 接收两个参数：第一个是数据文件名（比如 “books”），第二个是年份（比如 “24”），用来筛选对应年份的数据。

代码如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

{{- $dataFile := .Get 0 -}}
{{- $yearPrefix := .Get 1 -}}

{{- if not $dataFile -}}
  {{- errorf "medialist shortcode in %s: 缺少第一个参数 (数据文件名)。" .Page.Path -}}
{{- end -}}
{{- if not $yearPrefix -}}
  {{- errorf "medialist shortcode in %s: 缺少第二个参数 (年份)。" .Page.Path -}}
{{- end -}}

{{- $mediaData := index site.Data $dataFile -}}

{{- if $mediaData -}}
  {{- $count := 0 -}}
  {{- range $mediaData -}}
    {{- if (hasPrefix .type $yearPrefix) -}}
      {{- $count = add $count 1 -}}
      <div class="media">
        <div class="media-cover" style="background-image:url(\{\{ .coverurl \}\})"></div>
        <div class="media-meta">
          <div class="media-meta-item title"><a href="\{\{ .link \}\}" target="_blank" rel="noopener noreferrer">\{\{ .title \}\}</a><span style="float:right;font-weight:400">\{\{ .type \}\}</span></div>
          <div class="media-meta-item">
            <span class="author">\{\{ .author \}\}</span>
            <span class="star-score">\{\{ .starscore \}\}<span class="grey-star">\{\{ .greystar \}\}</span></span>
          </div>
          <div class="media-meta-item intro">\{\{ .intro | safeHTML \}\}</div>
        </div>
      </div>
    {{- end -}}
  {{- end -}}

  {{- if eq $count 0 -}}
    <p style="text-align: center; color: #888;">本年度暂无记录。</p>
  {{- end -}}
{{- else -}}
  <p>警告：找不到数据文件 data/\{\{ $dataFile \}\}.yaml (或 .json/.toml)</p>
{{- end -}}

这个 shortcode 的工作原理：

1. {{ $dataFile := .Get 0 }} 获取第一个参数（"books"）
2. {{ $yearPrefix := .Get 1 }} 获取第二个参数（"24"）
3. {{ range $mediaData }} 遍历数据文件中的所有条目
4. {{ if (hasPrefix .type $yearPrefix) }} 是最关键的一行，它检查每个条目的 type 字段（如 "24-01"）是否以我们传入的年份前缀（"24"）开头，只有匹配的条目才会被渲染成 HTML
5. 还增加了一个计数器，如果某一年份下没有任何记录，会显示“本年度暂无记录”

3. 修改 Markdown 文件

最后一步，就是把原来的 Markdown 文件里大段的 mediacard 调用，换成新的 medialist。

修改前 (2024年影剧部分):

1
2
3
4
5

{{< admonition type=tip title="影剧（20部）" open=false >}}
  {{< mediacard title="非诚勿扰3 (2023)" ... >}}
  {{< mediacard title="葬送的芙莉莲 (2023)" ... >}}
  ... (还有很多条)
{{< /admonition >}}

修改后:

1
2
3

{{< admonition type=tip title="影剧" open=false >}}
  {{< medialist "movies" "24" >}}
{{< /admonition >}}

原来几十行的内容，现在一行就够了，整个 Markdown 文件清爽了很多。

最终效果

这么修改之后，解决了之前维护困难的问题。

• Markdown 文件变干净了，只负责页面结构，不再包含具体数据。
• 数据管理方便，所有条目都在 .yaml 文件里，一目了然。
• 之后扩展也容易，这些数据可以很方便地在网站其他地方复用。

总的来说，对 Hugo 这种需要管理大量结构化数据的情况，用 Data Files 功能是个不错的选择。

小结

最终方案是用 data/books.yaml、data/movies.yaml 承载条目数据，再用 medialist Shortcode 按年份筛选并渲染。它牺牲了一点模板复杂度，换来了 Markdown 页面更清爽、数据更易批量维护的收益。后续可优化的方向，是继续抽象评分、分类和封面字段，并为数据文件增加更稳定的校验规则。

参考资料

• Hugo Data Templates
• Hugo Shortcodes

（2025-08-28@深圳）

适用场景

适合有持续写作习惯、希望在归档页展示产出节奏的 Hugo 博客。它也适合需要把站点数据做成轻量可视化模块的场景，比如文章数量、阅读记录或照片更新频率。

核心步骤

最近看到椒盐豆豉更新文章给博客增加了文章热力图，直接被种草。这种展现方式能直接的显示最近的产量（没眼看没眼看🤣），一方面能够作为催更动力让我别太懒，另一方面如果坚持写作贴满小瓷砖的话也能提供满满成就感。不过我最看重的一点是它使我回顾以往的文章更加容易也更有 feel，我可太爱循着日历回看文章这种形式了！

• 我是用 shortcodes 形式引入的代码，这样子在想引入的页面直接嵌入短代码即可，目前把成品放在了 归档 页面了。
• 我按着 Echart 官方文档和其他博主的样式教程修改了一些显示样式，使这个热力图控件和我的博客风格更搭，同时也调整了一下颜色控制部分的代码，使 Echart 图表自带的自动适配暗色模式的特性可以生效。

最终效果

热力图被放在归档页，作为文章列表之前的总览入口。它既能展示某段时间的写作密度，也能提醒自己哪些阶段断更较久，回看时比单纯的年月列表更有时间感。

小结

最终方案选择 Shortcode 封装 ECharts 配置，优点是复用方便、页面嵌入简单；取舍是需要维护一段图表配置代码，并关注主题暗色模式下的颜色表现。后续可以继续优化移动端显示、年份切换，以及多篇文章同日发布时的提示信息。

参考资料

• 椒盐豆豉：Hugo 博客热力图
• 引入热力图的主题提交

（2024-01-10@广州）

适用场景

适合需要在 Hugo 文章中集中展示多张照片、游记配图或作品集的页面。它的目标不是做完整图片管理系统，而是用尽量轻量的样式，让图片阅读更紧凑、更美观。

核心步骤

最近在给一系列博文配图，随着添加的图片多了之后，一直想实现的「图片瀑布流」的心思又活络起来了。Google 大法好，最终找到了图片瀑布流折腾记、Hugo 多图排版这样来 这两篇文章，两种不同的方法都很简单，都可以实现我想要的效果，感恩！

目前我主要在网站的两个地方进行应用，第一种是在文章中大量展示自己拍的照片时达到类似相册效果，这样既美观又省网页空间；另一种是专门的「回忆」页面，不断添加我自己拍的较为满意的照片，相当于照片画廊。

目前对网站图片进行了以下操作：

• 圆角处理：border-radius: 5px;
• 阴影效果：box-shadow: 0px 0px 5px rgba(0,0,0,0.3);
• 滑过放大：img:hover 和 transform 的纯 CSS 方案
• 多图排版：column-count 和 p:has(> img:nth-child) 的纯 CSS 方案

最终效果

小结

最终方案倾向于纯 CSS 实现，优点是简单、无需额外 JavaScript，和 Hugo 原本的 Markdown 图片写法也比较兼容；取舍是瀑布流控制能力不如专门图库组件精细。后续可以继续优化懒加载、移动端列数和图片说明文字，让相册页面在性能和可读性之间更平衡。

参考资料

• 图片瀑布流折腾记
• Hugo 多图排版这样来
• CSS3 图片 Hover 放大效果

（2023-12-16@广州）