C 黄撑的技术笔记
视觉实验室

MDX 视觉笔记组件示例：指标、卡片与决策流

用一组轻量 Astro 组件，把技术博客文章写成更适合扫描的科技风视觉笔记。

作者：黄撑 更新于 2026-06-29

这篇文章演示一组适合技术博客的 MDX 视觉笔记组件。它们都是静态 Astro 组件，可以直接插入文章正文，用来承载指标、功能说明、重点结论和决策过程。

指标概览

写作密度 3x

把零散要点收束成更容易扫描的卡片。

阅读路径 5 min

先看指标，再看说明，最后看决策流。

维护成本 Low

只依赖 Astro、MDX 和局部 CSS。

功能说明

指标卡片

MetricCard

适合展示数字、状态、耗时、比例等高扫描价值信息。

  • 支持简短说明
  • 支持蓝、青、紫、绿四种 tone
说明卡片

FeatureCard

适合解释一个能力、模块或写作块的作用。

  • 可放列表或短段落
  • 适合两栏或三栏布局

决策流程

什么时候使用视觉笔记组件

Input 先判断内容是否需要扫描

如果正文已经足够清楚，就继续使用普通 Markdown 段落。

Shape 再选择信息形态

数字用 MetricCard，能力说明用 FeatureCard，重点结论用 HighlightBox。

Publish 最后保持静态构建

新增文章后运行 npm test 和 npm run build，确认内容能被 Astro 正常构建。

MDX 写法

在文章顶部 import 组件，然后像普通标签一样组合使用：

import MetricCard from '../../../components/MetricCard.astro';
import VisualGrid from '../../../components/VisualGrid.astro';

<VisualGrid columns={2}>
  <MetricCard label="构建方式" value="Static" detail="Astro 构建期生成页面。" />
  <MetricCard label="交互复杂度" value="None" detail="不需要后端服务。" tone="cyan" />
</VisualGrid>