Hugo 文章中特殊结构的设计方案：流程图、统计图等可视化完全指南

① 静态图片（PNG/SVG 文件）
② 代码渲染（Mermaid / 纯 CSS / 纯 HTML+JS）
③ 外部服务嵌入（iframe / embed）

开始：你的图表需要什么？
│
├─ 需要交互（悬停、缩放、筛选）？
│   ├─ 是 → 【方案C】Chart.js / ECharts / D3.js（JS渲染）
│   └─ 否 ↓
│
├─ 图表数据会频繁更新？
│   ├─ 是 → 【方案B】Mermaid 代码块 或 JS渲染（改代码即改图）
│   └─ 否 ↓
│
├─ 图表结构复杂（精密排版、品牌设计）？
│   ├─ 是 → 【方案A】工具制图后导出 SVG/PNG
│   └─ 否 ↓
│
├─ 简单流程图 / 时序图 / 关系图？
│   └─ 【方案B】Mermaid 代码块（最省力）
│
└─ 简单统计数据（饼图、柱图）？
    └─ 【方案B+C】Mermaid 或 轻量 JS

content/
  posts/
    my-article/
      index.md          ← 文章（Page Bundle 方式）
      flow-chart.svg    ← 和文章同目录
      stats-2026.png

<!-- 普通图片 -->
![系统架构图](flow-chart.svg)

<!-- 带标题的图片（Hugo shortcode） -->
{{</* figure src="stats-2026.png" alt="2026年用户增长统计"
    caption="图1：2026年Q1用户增长趋势" width="800" */>}}

{{/* layouts/shortcodes/inline-svg.html */}}
{{ $svg := .Get 0 }}
{{ $file := .Page.Resources.Get $svg }}
{{ if $file }}
  {{ $file.Content | safeHTML }}
{{ end }}

{{</* inline-svg "flow-chart.svg" */>}}

<!-- SVG：矢量，任意分辨率清晰，文件小，可用 CSS 控制颜色 -->
<img src="diagram.svg" alt="架构图" width="800" height="500"
     loading="lazy" decoding="async" />

<!-- 暗色模式下反转 SVG 颜色（纯 CSS） -->
<style>
@media (prefers-color-scheme: dark) {
  img[src$=".svg"] {
    filter: invert(1) hue-rotate(180deg);
  }
}
</style>

[markup.goldmark.renderer]
  unsafe = true   # 允许 HTML 渲染（Mermaid 需要）

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
  mermaid.initialize({
    startOnLoad: true,
    theme: document.documentElement.dataset.theme === 'dark' ? 'dark' : 'default',
    flowchart: { useMaxWidth: true, htmlLabels: true },
    securityLevel: 'loose'
  });
</script>

<div class="mermaid-wrap">
  <div class="mermaid">{{ .Inner }}</div>
</div>

{{- if not (.Page.Scratch.Get "mermaid") -}}
  {{- .Page.Scratch.Set "mermaid" true -}}
  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true, theme: 'default' });
  </script>
{{- end -}}

{{</* mermaid */>}}
flowchart TD
    A[开始] --> B{判断条件}
    B -->|是| C[执行操作A]
    B -->|否| D[执行操作B]
    C --> E[结束]
    D --> E
{{</* /mermaid */>}}

flowchart LR
    subgraph 用户端
        A([用户请求]) --> B[浏览器缓存检查]
    end
    subgraph CDN层
        B -->|缓存未命中| C[CDN节点]
        B -->|缓存命中| Z([返回响应])
    end
    subgraph 服务端
        C -->|未命中| D[负载均衡器]
        D --> E[应用服务器1]
        D --> F[应用服务器2]
        E --> G[(数据库)]
        F --> G
    end
    G --> E --> C --> Z

sequenceDiagram
    actor 用户
    participant 前端
    participant API网关
    participant 认证服务
    participant 数据库

    用户->>前端: 点击登录
    前端->>API网关: POST /auth/login
    API网关->>认证服务: 验证凭据
    认证服务->>数据库: 查询用户信息
    数据库-->>认证服务: 返回用户数据
    认证服务-->>API网关: 签发 JWT Token
    API网关-->>前端: 200 OK + Token
    前端-->>用户: 登录成功

{{ $id := printf "chart-%s" (now.UnixNano | string) }}
{{ $type := .Get "type" | default "bar" }}
{{ $title := .Get "title" | default "" }}

<div class="chart-container" style="position:relative; max-width:700px; margin:2rem auto;">
  {{ if $title }}<p class="chart-title">{{ $title }}</p>{{ end }}
  <canvas id="{{ $id }}"></canvas>
</div>

<script>
(function() {
  const data = {{ .Inner | safeJS }};

  function initChart() {
    const ctx = document.getElementById('{{ $id }}');
    if (!ctx || !window.Chart) return;
    new Chart(ctx, {
      type: '{{ $type }}',
      data: data,
      options: {
        responsive: true,
        plugins: {
          legend: { position: 'top' }
        }
      }
    });
  }

  if (window.Chart) {
    initChart();
  } else {
    const s = document.createElement('script');
    s.src = 'https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js';
    s.onload = initChart;
    document.head.appendChild(s);
  }
})();
</script>

{{</* chart type="bar" title="2026年Q1各渠道用户增长" */>}}
{
  "labels": ["1月", "2月", "3月"],
  "datasets": [
    {
      "label": "自然搜索",
      "data": [1200, 1900, 2400],
      "backgroundColor": "rgba(59,130,246,0.7)"
    },
    {
      "label": "付费广告",
      "data": [800, 1100, 1600],
      "backgroundColor": "rgba(16,185,129,0.7)"
    }
  ]
}
{{</* /chart */>}}

<div id="echarts-demo" style="width:100%;height:400px;"></div>
<script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"></script>
<script>
const chart = echarts.init(document.getElementById('echarts-demo'), null, {
  renderer: 'svg'  // SVG渲染，清晰且可缩放
});

chart.setOption({
  tooltip: { trigger: 'axis' },
  legend: { data: ['注册用户', '活跃用户', '付费用户'] },
  xAxis: {
    type: 'category',
    data: ['2025-Q3', '2025-Q4', '2026-Q1', '2026-Q2']
  },
  yAxis: { type: 'value', name: '用户数（万）' },
  series: [
    {
      name: '注册用户',
      type: 'line',
      smooth: true,
      data: [120, 145, 180, 215],
      areaStyle: { opacity: 0.1 }
    },
    {
      name: '活跃用户',
      type: 'line',
      smooth: true,
      data: [80, 98, 125, 158]
    },
    {
      name: '付费用户',
      type: 'bar',
      data: [12, 18, 26, 35]
    }
  ]
});

// 响应窗口大小变化
window.addEventListener('resize', () => chart.resize());
</script>

<div class="css-bar-chart" aria-label="季度收入对比">
  <style>
  .css-bar-chart {
    display: flex;
    align-items: flex-end;
    gap: 1.5rem;
    height: 200px;
    padding: 1rem;
    border-bottom: 2px solid #e2e8f0;
  }
  .css-bar {
    flex: 1;
    background: linear-gradient(to top, #3b82f6, #93c5fd);
    border-radius: 4px 4px 0 0;
    position: relative;
    transition: opacity 0.2s;
    animation: barGrow 0.8s cubic-bezier(0.34, 1.56, 0.64, 1) both;
    transform-origin: bottom;
  }
  .css-bar:hover { opacity: 0.8; }
  .css-bar::after {
    content: attr(data-value);
    position: absolute;
    top: -1.5rem;
    left: 50%;
    transform: translateX(-50%);
    font-size: 0.75rem;
    font-weight: 600;
    color: #1e40af;
    white-space: nowrap;
  }
  .css-bar::before {
    content: attr(data-label);
    position: absolute;
    bottom: -1.5rem;
    left: 50%;
    transform: translateX(-50%);
    font-size: 0.75rem;
    color: #64748b;
    white-space: nowrap;
  }
  @keyframes barGrow {
    from { transform: scaleY(0); }
    to   { transform: scaleY(1); }
  }
  </style>

  <div class="css-bar" style="height:60%" data-value="120万" data-label="Q1"></div>
  <div class="css-bar" style="height:75%" data-value="150万" data-label="Q2"></div>
  <div class="css-bar" style="height:88%" data-value="176万" data-label="Q3"></div>
  <div class="css-bar" style="height:100%" data-value="200万" data-label="Q4"></div>
</div>

<svg viewBox="0 0 600 200" xmlns="http://www.w3.org/2000/svg"
     role="img" aria-label="三步流程图">
  <defs>
    <marker id="arr" markerWidth="8" markerHeight="8"
            refX="6" refY="3" orient="auto">
      <path d="M0,0 L0,6 L8,3 z" fill="#64748b"/>
    </marker>
  </defs>

  <!-- 步骤1 -->
  <rect x="20" y="70" width="140" height="60"
        rx="8" fill="#dbeafe" stroke="#3b82f6" stroke-width="2"/>
  <text x="90" y="97" text-anchor="middle"
        font-family="sans-serif" font-size="14" fill="#1e40af">
    <tspan x="90" dy="0" font-weight="600">步骤一</tspan>
    <tspan x="90" dy="18" font-size="12">收集需求</tspan>
  </text>

  <!-- 箭头1 -->
  <line x1="160" y1="100" x2="210" y2="100"
        stroke="#64748b" stroke-width="2" marker-end="url(#arr)"/>

  <!-- 步骤2 -->
  <rect x="210" y="70" width="140" height="60"
        rx="8" fill="#dcfce7" stroke="#22c55e" stroke-width="2"/>
  <text x="280" y="97" text-anchor="middle"
        font-family="sans-serif" font-size="14" fill="#166534">
    <tspan x="280" dy="0" font-weight="600">步骤二</tspan>
    <tspan x="280" dy="18" font-size="12">设计方案</tspan>
  </text>

  <!-- 箭头2 -->
  <line x1="350" y1="100" x2="400" y2="100"
        stroke="#64748b" stroke-width="2" marker-end="url(#arr)"/>

  <!-- 步骤3 -->
  <rect x="400" y="70" width="140" height="60"
        rx="8" fill="#fef3c7" stroke="#f59e0b" stroke-width="2"/>
  <text x="470" y="97" text-anchor="middle"
        font-family="sans-serif" font-size="14" fill="#92400e">
    <tspan x="470" dy="0" font-weight="600">步骤三</tspan>
    <tspan x="470" dy="18" font-size="12">开发上线</tspan>
  </text>
</svg>

{{/* layouts/partials/diagrams.html —— 只在需要时加载 */}}

{{ if .Page.Scratch.Get "mermaid" }}
<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
  mermaid.initialize({
    startOnLoad: true,
    theme: window.matchMedia('(prefers-color-scheme: dark)').matches
      ? 'dark' : 'default'
  });
</script>
{{ end }}

{{ if .Page.Scratch.Get "chartjs" }}
<script src="https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js"
        defer></script>
{{ end }}

{{ partial "diagrams.html" . }}