博客与文档内容块

这些组件可直接写进文档或博客，无需文章作者编写 Vue。每个组件下面都有实际效果和可复制 MDC。集中交互演示见 组件演示。

ArticleSummary：摘要与结论

适合文章开头的阅读要点、章节结论和故障排查摘要。title 默认“阅读要点”，icon 默认 lucide-list-checks。默认插槽支持完整 Markdown，可选 takeaway 插槽放行动建议。

::article-summary{title="上线前检查"}
- 核对生产环境变量。
- 跑通关键页面和内容查询。

#takeaway
结论：先验证，再发布。
::

ExpandBox：折叠补充说明

适合 FAQ、原始输出和较长的补充解释。基于原生 details/summary，无需 JavaScript 就能展开；支持鼠标、Enter 与空格。

pnpm content:check

::expand-box{title="为什么使用组件而不是截图？"}
文字与代码可以复制，样式会跟随站点主题。

```bash
pnpm content:check
```
::

默认展开使用 :open="true"，或在组件 YAML 里写 open: true。

LinkCard：参考资料与文档入口

卡片只将标题作为链接，正文仍可以放其他 Markdown 链接，不会嵌套交互元素。

::link-card{title="MDC 写法与注册" to="/docs/简单文档/components/mdc-guide" description="理解 props、插槽与嵌套语法。"}
也可以先阅读 [组件索引](/docs/简单文档/components/api)。
::

外链写 target="_blank"。支持站内链接及 http/https/mailto/tel；拒绝危险协议和 URL 中内嵌的用户名密码。

QuoteBlock：带署名的引用

使用 figure、blockquote 与 cite 保留引用语义。正文可写段落；author 为署名，source 为来源，to 为可选来源链接。没有署名或来源时不显示空 footer。

::quote-block{author="本文作者" source="写作建议"}
把复杂问题拆成可以验证的步骤，让读者知道下一步要做什么。
::

StatGrid：指标网格

items 是必填数组，每项包含 label、value（string 或 number）和可选 description。columns 为 2、3 或 4，默认 3；手机始终单列。数值由作者提供，组件不执行统计，也不代表真实监控数据。

示例设备

12

以下数值仅用于排版演示

检查项

8

完成比例

100%

::stat-grid
---
columns: 3
items:
  - label: 示例设备
    value: 12
    description: 以下数值仅用于排版演示
  - label: 检查项
    value: 8
  - label: 完成比例
    value: 100%
---
::

DocTimeline 与 TimelineItem：过程与更新日志

外层 label 设置可访问名称（默认“时间线”）。每个条目的 title 必填，date 是显示文字，datetime 为可选机器可读日期，正文插槽可以放列表和代码。条目应放在 DocTimeline 内。

1. 2026-10-01

   准备版本

   整理变更列表与验收标准。

2. 2026-10-02

   验证版本

   • 核对内容。
   • 执行浏览器回归。

:::doc-timeline{label="示例版本记录"}
::timeline-item{title="准备版本" date="2026-10-01" datetime="2026-10-01"}
整理变更列表与验收标准。
::
::timeline-item{title="验证版本" date="2026-10-02" datetime="2026-10-02"}
- 核对内容。
- 执行浏览器回归。
::
:::

TaskChecklist：读者检查清单

items 为必填数组，每项有 label、可选 description 和 checked（默认 false）。title 默认“检查清单”，readonly 默认 false。可勾选时显示完成数，并通过状态区域向辅助技术播报。

::task-checklist
---
title: 示例发布清单
items:
  - label: 已核对链接
    checked: true
  - label: 已检查手机排版
    description: 确认表格与图片不会挤出正文
  - label: 已阅读部署说明
---
::

勾选状态仅存在于当前组件，刷新页面恢复作者提供的初始状态；没有账号、服务器存储或跨设备同步。只展示状态时设置 readonly: true，复选框会禁用。空数组显示 0 / 0，不会出现无效百分比。

ImageGallery：图片网格与大图预览

images 为必填数组，每项有 src、alt 和可选 caption。alt 应准确描述图像，不省略。title 默认“图片画廊”，columns 为 2 或 3（默认 2），手机单列。

1 / 2 关闭预览

内容渲染流程

上一张 下一张

::image-gallery
---
title: 文档工作流
images:
  - src: /images/mdc/render-flow.svg
    alt: Markdown 通过 Content AST 渲染为 Vue 组件
    caption: 内容渲染流程
  - src: /images/mdc/publish-flow.svg
    alt: 编写、验证与发布三个阶段
    caption: 文档发布流程
---
::

点击图片或聚焦后按 Enter 打开预览；左右键或“上一张/下一张”切换，Esc 或“关闭预览”关闭，焦点返回触发按钮。预览使用原生 dialog，背景不能误操作。网格图片延迟加载，不安全图片 URL 不渲染，支持站内及 HTTP(S) 图片；空数组不显示图片。

图库图注直接使用每项的 caption，不受普通 Markdown 图片的全站图注开关影响。示例 SVG 是本仓库为说明文档工作流制作的图示。