卡片
{.cards} 的链接列表排出导航卡片网格；需要图标、徽章、图片时改用 shortcode。卡片（Cards）是一组并列的链接：每张卡片一个链接标题加一句描述，网格随容器宽度自适应。适合栏目首页、「接下来读什么」与几条并列路径的入口。不适合排版正文段落（用普通段落）或做图片墙（用画廊）。
最简例子
带 {.cards} 的链接列表就是卡片。链接是标题，— 之后是描述。
整张卡片是点击热区，不只是标题文字。没有 columns 参数：列数由容器宽度决定，窄屏收成一列。
只有标题的卡片
描述可以省略。一行一个链接，{.cards} 收尾。
松散列表与多段描述
一句话装不下时改用松散列表：链接单独一段，描述另起一段，列表项之间空一行。标题独占一行，描述在标题下方。{.cards} 仍然紧贴最后一段，中间 不能有空行。
图标与徽章
链接列表不支持图标、徽章、图片与多段描述，这些用 cards / card shortcode。icon 是恰好一对 Font Awesome class，badge 是一段纯文本。
图标格式不符（不是 fa-solid fa-xxx 这样的一对 class）时构建失败，不会静默丢弃。
Markdown 正文
card 的正文按页面级 Markdown 渲染：行内代码、强调、链接、列表都可以。title、badge 这些参数是纯文本，不解析 Markdown。
hugo mod get github.com/pgsty/oink。推荐方式，升级只需改一行版本号。
无需安装 Go：
git submodule add- 主题落在
themes/oink
不写 link 的卡片渲染成加粗标题，不生成链接。
带图片的卡片
image 与  的解析顺序一致：页面资源 → 全局资源 assets/ → 静态路径 /images/… → 远程 URL。本地资源带上固有尺寸，避免加载跳版。
image 必须配一个替代文字来源：image_alt="…"（有信息的图）或 decorative=true（纯装饰）。两个都写、两个都不写都会构建失败。
卡片图片不参与图片缩放，整张卡片本身已经是链接。
栏目首页的自动卡片
栏目首页（_index.md）不需要手写卡片列表：主题读子页的 title、description、icon 自动生成一组卡片。本站在 hugo.yml 中全局启用：
单个栏目可以在自己的 front matter 里覆盖，也可以用 cascade 把选择推给整棵子树：
自动卡片与手写卡片使用同一套 td-content-card 样式，区别只在数据来源。栏目首页不要手写子页清单：手写清单会与侧栏不同步。要排的内容不是本栏目的子页时（例如混合站外链接、跨栏目推荐），才在正文里手写卡片。相关键的完整定义见配置总览。
两种形态的选择
| 你要的 | 用哪种 |
|---|---|
| 一句话描述的链接网格 | {.cards} 链接列表 |
| 图标、徽章、图片 | cards / card shortcode |
| 描述里要列表、代码、多段 | cards / card shortcode |
| 没有链接的卡片 | cards / card shortcode |
| 本栏目的子页 | 什么都不写，靠 section_index: cards |
链接列表在 GitHub 上仍是一个链接列表，shortcode 不是。能用原生形态时用原生形态。
输出形态
| 输出 | 呈现 |
|---|---|
| HTML | 原生形态是 <ul class="cards">；shortcode 形态是 <div class="td-content-cards"> + 每张 <article class="td-content-card">。两者都是纯 CSS 网格，不加载脚本 |
| 打印 | 原生形态竖排，shortcode 形态收成两列；两者的单张卡片都避免跨页断开 |
| Markdown | 原生形态原样输出链接列表；shortcode 形态输出 - [标题](链接) (徽章) — 描述 |
| RSS | 与 HTML 同样的标记（没有站点 CSS 时是一份可读的链接清单） |
参数参考
原生形态：
card 的参数（cards 自身不接受任何参数）：
没有 cols、columns、accent、desc、color 参数；未知参数一律构建失败。
限制与常见问题
{.cards}只认无序列表：有序列表加了这个标记不会变成卡片。{.cards}必须紧贴列表：中间空一行、或缩进进列表项，标记被静默丢弃，构建不报错，列表仍是列表。渲染结果不是卡片时先检查这一行。card只能待在cards里：单独使用、或放进别的 shortcode，构建失败并指出位置。- 列数不可配：网格按容器宽度自适应，只有栏目首页的自动卡片能用
params.ui.section_index_columns指定列数。 - 卡片不放长文：描述超过两行时改用正文段落或提示块。