在文章中使用组件

普通段落、列表和短表格仍然直接写 Markdown。需要折叠长说明、查找多行数据，或者把接口参数集中展示时，再加入组件。docs 和 blog 的写法相同，不需要为每篇文章导入 Vue 文件。

先知道名字怎么写

组件名转换为短横线写法：ArticleSummary 写成 ::article-summary，DataTable 写成 ::data-table。块组件以 :: 开始和结束，行内术语使用单个 :。

字符串属性可以放在花括号里；数组和对象放在组件内部的 YAML 属性区。嵌套组件时，外层使用 :::，内层使用 ::。详细规则见 MDC 语法与注册。

给长文章一个入口

ArticleSummary 适合先交代阅读范围，ExpandBox 用来收起暂时用不到的细节。下面展示实际效果，随后是同一段内容的源码。

::article-summary{title="这份操作说明包含什么"}
- 准备运行环境。
- 检查设备清单中的地址。
- 导出报告后核对失败项。
::

::expand-box{title="只想先看运行步骤？"}
可以先按正文操作，遇到连接失败时再回来看超时、凭据和网络可达性的说明。
::

相关阅读使用 LinkCard，引用并标注来源使用 QuoteBlock，几个统计数字使用 StatGrid，按时间记录过程使用 DocTimeline 和 TimelineItem。这些组件的 属性和示例 放在同一页。

让较长的清单能查找

两三行对照用普通表格就够了。下面的 DataTable 演示搜索、列排序和分页：输入“接入”只看接入设备，点击“端口数”可改变排序，清空搜索后可以翻到下一页。

::data-table
---
title: 设备清单示例
pageSize: 2
columns:
  - key: name
    label: 设备
  - key: ports
    label: 端口数
  - key: enabled
    label: 启用
rows:
  - name: 核心交换机
    ports: 48
    enabled: true
  - name: 接入交换机 2
    ports: 24
    enabled: true
  - name: 接入交换机 10
    ports: 8
    enabled: false
---
::

columns.key 对应 rows 中的键。端口数写成数值，启用状态写成布尔值；0 和 false 会保留，空值显示为“—”。搜索、排序和分页都在当前页面完成，不连接后端数据源。

把接口、参数和响应放在一起

ApiEndpoint 展示方法与路径，ParameterTable 展示参数。请求和响应分别写进 request、response 插槽。

以下是虚构的报告查询接口，用来说明组件布局；复制这段代码不会创建接口，也不会发送请求。

GET /api/reports/demo HTTP/1.1

{ "id": "demo", "status": "ready" }

:::api-endpoint{title="报告查询示例" method="GET" path="/api/reports/{id}" :status="200"}
::parameter-table
---
parameters:
  - name: id
    type: string
    location: path
    required: true
    description: 要查询的报告标识
---
::

#request
```http
GET /api/reports/demo HTTP/1.1
```

#response
```json
{ "id": "demo", "status": "ready" }
```
:::

参数还可以写 default、enum 和 deprecated。属性由作者填写，组件不会自动从 TypeScript 或 OpenAPI 推导。

解释术语，留一道自测

页面先经过 SSRSSR服务端渲染：服务器先生成页面的初始 HTML，再交给浏览器。，浏览器随后接管交互。点击这句话里的 SSR 就能看解释，不必跳出正文。

页面先经过 :glossary-term{term="SSR" definition="服务端渲染：服务器先生成页面的初始 HTML，再交给浏览器。"}，浏览器随后接管交互。

ContentQuiz 适合操作指南中的小问题，帮助读者核对是否读懂了参数：

::content-quiz
---
question: answer 为 1 时，哪一项是正确选项？
choices:
  - 第一项
  - 第二项
  - 第三项
answer: 1
explanation: answer 从 0 开始计数，0 是第一项，1 是第二项。
---
::

自测只在当前页面显示反馈，不上传成绩；答案也在公开内容里，不能用于保密考试。

附上文件和核对清单

DownloadCard 使用已存在的文件地址，不生成文件。站内文件可以放在 public/ 中，例如 public/examples/devices.example.json 对应下面的下载地址。

::download-card{title="设备清单示例" href="/examples/devices.example.json" filename="devices.example.json" description="用于演示下载，字段需按实际工具格式调整。"}
::

TaskChecklist 可以给操作说明收尾。读者可以勾选，但刷新页面会恢复作者设置的初始状态。

::task-checklist
---
title: 发布前核对
items:
  - label: 示例地址和数据可以公开
  - label: 下载文件存在，链接能打开
  - label: 组件在手机上也能操作
---
::

图片和其他组件去哪里找

• 多张截图用 ImageGallery：支持点击放大、左右键切换和 Esc 关闭，见 图库示例。
• 同一对象修改前后的图片用 ImageCompare：两张图尽量保持相同尺寸和构图，见 图片对比演示。
• 老文章中的卡片、标签页、文件树和代码树可以继续使用。27 个公共组件的清单见 常用组件。
• 完整参数见 文章内容组件 和 数据、API 与阅读交互组件。

保存后检查

先运行 pnpm content:check，检查站内链接、图片和已覆盖的组件属性，再运行 pnpm build 并打开页面确认效果。检查通过后仍要手动试一次交互，尤其是嵌套组件、命名插槽和下载文件。

写作实例见 最近给文档站补了些什么。