给 Hugo 博客加上卡片式能力总览：Mermaid + 自定义 shortcode 实践

Wed, 22 Apr 2026 00:00:00 +0000

最近看到一个 AIQA 能力总览的 landing 页：顶部卡片阵列、中间带坐标的 SVG 流程图、配色和阴影都很克制。我想把这种表达力带进博客，但不想每次写文章都重画一遍 SVG。于是重新梳理了一下 Hugo 这边的做法，落地成两个 shortcode 和一段作用域化的 CSS。

一、问题是什么

照搬示例页面有几个硬伤：

硬坐标 SVG（x="340" y="230" 那种）一改文案就要重算坐标，和 markdown 的轻量写作完全反着来。
样式耦合：示例把所有 CSS 变量都挂在 :root 上，塞进 post 会污染全站命名空间。
Goldmark unsafe=true 虽然已经开了，但直接在 md 里糊 200 行 HTML，语义层级乱掉。

所以目标是：流程图文本化、卡片样式作用域化、写作体验仍然是 markdown。

二、技术栈取舍

📊

Mermaid 代替 SVG

流程图用文本语法描述，diff 友好，无需关心坐标。按需加载，不用 Mermaid 的页面零开销。

🎴

Shortcode 组合卡片

capability-grid + capability-card 两级组合，cols 和 color 用参数控制，写法贴近 markdown。

🎯

CSS 作用域隔离

所有变量和类名挂在 .cap-overview 下，不会污染主题的 :root，未来换主题也不冲突。

三、流程图：Mermaid 代替手画 SVG

写作时只要这样：

{{< mermaid >}}
graph LR
 A[Markdown 源文件] --> B[Hugo 构建]
 B --> C[Shortcode 展开]
 C --> D[静态 HTML]
 D --> E[浏览器渲染]
 E --> F{含 Mermaid?}
 F -- 是 --> G[CDN 加载 mermaid.esm.min.mjs]
 F -- 否 --> H[零额外开销]
 G --> I[文本语法转 SVG]
{{< /mermaid >}}

渲染结果：