一、如何使用组件
站点所有文章均使用 MDX 编写。在任意 .mdx 文件顶部通过 import 引入组件后即可像普通 HTML 标签一样使用:
import CodeBlock from '@/components/CodeBlock.astro';<CodeBlock type="terminal" code={`ls -la`} />要点:
- 路径别名
@/等价于项目根目录的src/,即@/components/CodeBlock.astro指向src/components/CodeBlock.astro。 - 组件既可以自闭合
<CodeBlock />(属性写在标签内),也可以成对<Callout>...</Callout>(内容写在标签之间,即“插槽 / slot”)。需要正文内容的组件(如Callout、StepCard、FAQ的插槽模式)必须用成对写法。 - 组件属性值分为两类:字符串(直接写
title="提示")与表达式(用花括号包裹,如items={[{question:'...', answer:'...'}]})。数组、对象、数字、布尔值必须加花括号。 - 所有内置组件均已适配深色模式,无需额外处理。
本站约定:禁止使用 Markdown 原生围栏代码块(三个反引号)。所有块级代码一律用 <CodeBlock> 组件渲染。原因见 src/styles/global.css 第五部分注释——Markdown 围栏块会被渲染成 <pre><code> 后套用行内代码样式,导致视觉异常。内联代码(行内 code)仍可用单个反引号。
二、组件一览
| 组件 | 文件 | 主要用途 |
|---|---|---|
CodeBlock | CodeBlock.astro | 5 种差异化代码块(代码 / 终端 / 网络 / 配置 / 日志) |
Callout | Callout.astro | 备注、提示、警告等强调框(8 种类型),支持折叠 |
StepCard | StepCard.astro | 带序号圆圈与连接线的操作步骤卡片 |
AuthorCard | AuthorCard.astro | 文章作者信息卡片(头像、简介、社交链接、公众号二维码) |
DownloadCard | DownloadCard.astro | 下载链接卡片(内置 11 种网盘图标) |
BilibiliPlayer | BilibiliPlayer.astro | B 站视频 16 响应式嵌入 |
FAQ | FAQ.astro | 折叠式常见问题,带搜索框;支持 items 与插槽两种模式 |
LinkButton | LinkButton.astro | 链接按钮(4 种样式、3 种尺寸、可选图标) |
References | References.astro | GB/T 7714 标准参考文献列表 |
ComparisonTable | ComparisonTable.astro | 特性对比表,支持 ✅/❌ 状态标签 |
Copyright | Copyright.astro | 文章末尾版权声明区块 |
Timeline | Timeline.astro | 时间轴 |
ImageSearch | ImageSearch.astro | EVE-NG 镜像名称搜索(IOL / QEMU 筛选) |
Announcement | Announcement.astro | 站点公告(滚动条 + 弹窗),配置来自 announcements.json |
Categories | Categories.astro | 首页技术栏目卡片,配置来自 categories.json |
三、通用格式调整(设计系统)
在组合组件、编写正文时,可以直接套用全局样式系统,无需重复造轮子。
3.1 设计变量(CSS 变量)
在组件或 <style> 中可通过 var() 引用。常用变量:
| 变量 | 含义 | 示例值 |
|---|---|---|
--brand-* | 品牌主色阶(500 为基准) | --brand-500: #3b82f6 |
--color-text / --color-text-light / --color-text-muted | 正文 / 次级 / 弱化文字色 | — |
--color-bg / --color-bg-card / --color-bg-secondary | 背景 / 卡片背景 / 次级背景 | — |
--color-border | 边框色 | — |
--color-primary / --success-500 / --warning-500 / --error-500 / --info-500 | 语义色 | — |
--space-xs…--space-3xl | 间距阶梯(0.25→4rem) | --space-md: 1rem |
--radius-sm…--radius-xl | 圆角(4→16px) | --radius-lg: 12px |
--shadow-sm…--shadow-xl | 阴影 | — |
--transition-fast/normal/slow | 过渡时长 | 150ms/300ms/500ms |
--font-sans / --font-mono | 正文字体 / 等宽字体 | — |
文章级的品牌色由 Front Matter 的 brandColor 字段控制;Callout、Timeline、LinkButton、AuthorCard 等组件会读取 --brand-color(由主题层注入),从而与栏目配色保持一致。
3.2 工具类(直接加 class)
下列工具类可直接用于 Markdown 段落或组件的 class 属性:
- 文本:
.text-center.text-left.text-right.text-primary.text-muted.text-sm.text-xs - 间距:
.mt-0/1/2/3/4、.mb-0/1/2/3/4(对应--space-*阶梯) - 排版:
.text-center - 栅格:
.grid+.grid-cols-2 / -3 / -4(移动端自动降为单列) - 弹性:
.flex.flex-col.items-center.justify-center.justify-between.gap-1/2/3 - 其他:
.w-full.hidden.card.btn.btn-primary.badge.badge-success/-warning/-error/-info.divider.kbd
示例:用栅格并排两个下载卡片。
<div class="grid grid-cols-2 gap-3"><DownloadCard title="镜像A" href="https://..." /><DownloadCard title="镜像B" href="https://..." type="aliyun" /></div>3.3 深色模式
所有组件均已适配三种深色触发方式,无需作者干预:
prefers-color-scheme: dark(系统级)- 给祖先元素加
.dark-modeclass - 给祖先元素加
data-theme="dark"属性
3.4 Callout 指令语法(免 import 速记)
除 <Callout> 组件写法外,正文里还可用 remark-directive 语法直接写提示框,无需 import:
:::tip[这是标题]这里是提示框的正文,支持 **加粗**、行内 `code` 与[链接](https://example.com)。::::::warning{collapsible="true"}[可折叠的注意事项]默认收起,点击标题展开。:::语法规则:
- 以
:::开头、:::结尾;类型名紧跟其后(note/tip/info/warning/danger/success/question/example)。 - 标题写在方括号
[ ]内(可选,省略则使用类型默认标题如“提示”)。 - 属性写在花括号
{ }内,字符串值需加引号:{collapsible="true"}、{collapsed="true"}。 - 指令模式的内容仅支持基础 Markdown(加粗、斜体、行内代码、链接),复杂排版建议改用
<Callout>组件写法。
四、组件详解
4.1 CodeBlock — 代码块
项目中最核心的内容组件,提供 5 种视觉风格差异化的代码块,并内置“复制”按钮(复制时会按类型智能剥离提示符 / 设备前缀)。
属性(来自 CodeBlock.types.ts)
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
type | 'code' | 'terminal' | 'network' | 'config' | 'log' | 必填 | 代码块类型,决定配色与高亮逻辑 |
code | string | 必填 | 代码文本内容 |
lang | string | — | 语言标识,仅 type="code" 时用(如 python、go、json) |
shell | 'bash' | 'sh' | 'zsh' | 'cmd' | 'powershell' | 'pwsh' | 'bash' | 仅 terminal 有效,影响标签名与复制剥离规则 |
vendor | 'huawei' | 'cisco' | 'h3c' | 'juniper' | 'arista' | 'ruijie' | 'huawei' | 仅 network 有效,标签栏显示厂商名 |
level | 'error' | 'success' | 'warning' | 'info' | 'debug' | 'error' | 仅 log 有效,标签栏显示级别名 |
filePath | string | — | 仅 config 有效,显示配置文件路径并按后缀推断高亮语言 |
label | string | — | 额外标签(如中间件名),config 下常配合 filePath |
title | string | — | 覆盖默认标签文字(CODE/TERMINAL/NETWORK/CONFIG/LOG) |
各类型说明与示例
type="code" — 编程语言,蓝色主题,Shiki 多语言高亮:
<CodeBlock type="code" lang="python" code={`import osprint(os.getcwd())`} />type="terminal" — 终端交互,绿色主题,自动区分 $/#/> 提示符与输出,复制时剥离提示符:
<CodeBlock type="terminal" code={`$ npm installadded 245 packages in 30s$ npm run buildBuild complete!`} /><!-- Windows cmd / PowerShell 用 shell 指定 --><CodeBlock type="terminal" shell="cmd" code={`> dir`} /><CodeBlock type="terminal" shell="powershell" code={`PS> Get-Process`} />type="network" — 网络设备配置,橙色主题,自动高亮 IP、接口名等关键字,复制时剥离 [Huawei]/<Huawei>/Router# 等设备前缀:
<CodeBlock type="network" vendor="huawei" code={`interface GigabitEthernet0/0ip address 192.168.1.1 255.255.255.0no shutdown`} />type="config" — 配置文件,紫色主题,支持 filePath 与 label:
<CodeBlock type="config" code={`server { listen 80; server_name example.com; root /var/www/html;}`} filePath="/etc/nginx/nginx.conf" label="Nginx" />type="log" — 日志与错误,红色主题,自动高亮 ERROR/WARN/INFO 等关键字,level 控制标签:
<CodeBlock type="log" level="error" code={`ERROR 2026-07-17 main.py:42 Connection refusedWARN 2026-07-17 config.py:18 Using default settingsINFO 2026-07-17 server.py:100 Listening on :8080`} />- 终端命令一律用
terminal,不要用code,否则提示符会被当成语法高亮,且复制会带$。 - 网络设备配置用
network(记得选vendor),日志用log,配置片段用config+filePath。 - 普通源码片段用
code+lang。
4.2 Callout — 标注框
用于在文章中插入提示、警告、信息等强调内容。支持 8 种类型与折叠。
属性(组件写法 <Callout>)
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
type | 'note' | 'tip' | 'info' | 'warning' | 'danger' | 'success' | 'question' | 'example' | 'note' | 类型,决定配色与默认标题 |
title | string | 类型默认标题 | 自定义标题 |
icon | string | 类型默认图标 | 自定义 SVG 图标(直接传 SVG 字符串) |
collapsible | boolean | false | 是否可折叠 |
collapsed | boolean | false | 折叠时是否默认收起(需 collapsible) |
dismissible | boolean | false | 预留:是否可关闭 |
id | string | 自动生成 | 元素 id(一般无需指定) |
8 种类型对照
| 类型 | 默认标题 | 配色 |
|---|---|---|
note | 备注 | 蓝 |
tip | 提示 | 绿 |
info | 信息 | 青 |
warning | 注意 | 黄 |
danger | 危险 | 红 |
success | 成功 | 绿 |
question | 问题 | 紫 |
example | 示例 | 靛蓝 |
组件写法示例
<Callout type="tip" title="小技巧">这里写正文,支持 **Markdown**、行内 `code` 与[链接](https://example.com)。</Callout><Callout type="danger" collapsible collapsed title="排错清单">点击标题可展开。</Callout>指令写法(见 3.4 节)更简洁,正文里推荐用指令写法。
4.3 StepCard — 步骤卡片
展示操作步骤或流程,序号为圆圈 + 虚线连接线,最后一步显示 ✓。内容通过插槽传入,通常用有序列表 <ol>。
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
title | string | '' | 卡片标题(可选,显示在顶部带下划线区) |
icon | string | '' | 标题前的 SVG 图标字符串(可选) |
size | 'sm' | 'md' | 'lg' | 'md' | 序号圆圈尺寸 |
type | 'default' | 'success' | 'warning' | 'info' | 'default' | 配色类型(default 跟随品牌色) |
示例
<StepCard title="初始化配置" type="success"><ol> <li>打开终端,进入项目目录。</li> <li>执行 <code>npm install</code> 安装依赖。</li> <li>运行 <code>npm run dev</code> 启动本地服务。</li></ol></StepCard>size 控制圆圈大小(sm 1.5rem / md 1.75rem / lg 2rem);type 控制整体配色(默认跟随品牌蓝,另可选绿/黄/青)。组件内部会自动把 <ol> 渲染成带圆圈序号的步骤,把 <ul> 渲染成同色系小圆点列表。
4.4 AuthorCard — 作者卡片
展示文章作者信息,支持头像、简介、社交链接、博客与公众号二维码弹窗。
属性
| 属性 | 类型 | 说明 |
|---|---|---|
name | string | 作者姓名(必填) |
role | string | 职务 / 头衔 |
avatar | string | 头像图片 URL |
avatarUrl | string | 点击头像跳转的链接(有则头像可点击) |
bio | string | 作者简介 |
links | { label: string; url: string }[] | 自定义链接列表 |
blogUrl | string | 博客地址(显示“博客”按钮) |
wechatQrCode | string | 公众号二维码图片 URL(显示“微信公众号”按钮,点击弹出) |
示例
<AuthorCardname="张三"role="高级网络工程师"avatar="/avatars/zhangsan.png"avatarUrl="https://blog.example.com"bio="专注数据中心网络与自动化运维。"blogUrl="https://blog.example.com"wechatQrCode="/qrcode/wechat.png"links={[ { label: 'GitHub', url: 'https://github.com/xxx' }, { label: '邮箱', url: 'mailto:me@example.com' }]}/>4.5 DownloadCard — 下载卡片
下载链接卡片,内置 11 种网盘 SVG 图标,按钮默认新窗口打开。
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
title | string | 必填 | 文件 / 资源标题 |
href | string | 必填 | 下载地址(新窗口打开) |
description | string | '' | 描述 |
size | string | '' | 文件大小,如 1.2 GB |
version | string | '' | 版本号,如 2.3 |
btnText | string | '前往下载' | 按钮文字 |
type | 见下 | 'baidu' | 网盘类型,决定左侧图标 |
tag | string | '' | 标题后的小标签(如“官方”“VIP”) |
type 可选值(共 11 种):baidu / widely / tiandun / lanzou / aliyun / chengtong / pan123 / hi168 / guanwang / quark / xunlei。
示例
<DownloadCardtitle="EVE-NG 社区版镜像"href="https://pan.baidu.com/s/xxx"size="1.8 GB"version="2.0.1"type="baidu"tag="官方"description="社区版,含常用网络设备镜像"/><DownloadCard title="文档合集" href="https://www.aliyundrive.com/xxx" type="aliyun" />4.6 BilibiliPlayer — B 站视频
16
响应式嵌入 B 站播放器。属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
bvid | string | '' | B 站 BV 号,如 BV1kj59zGEqV |
aid | string | '' | 视频 av 号(与 bvid 二选一) |
p | number | 1 | 分 P 编号 |
cid | string | '' | 视频 CID(可选) |
autoplay | boolean | false | 是否自动播放 |
示例
<BilibiliPlayer bvid="BV1kj59zGEqV" p={2} />两个必填其一:bvid 或 aid。若都不传,组件会渲染占位提示“请传入 bvid 或 aid 参数”。
4.7 FAQ — 常见问题
折叠式问答列表,顶部带搜索框(按问题文本过滤),支持两种数据模式。
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
items | { question: string; answer: string }[] | — | 数据模式:直接传问答数组 |
collapsible | boolean | true | 是否允许点击展开/收起 |
模式一:items 数据模式(answer 支持 HTML)
<FAQitems={[ { question: '如何安装依赖?', answer: '运行 <code>npm install</code> 即可。' }, { question: '支持深色模式吗?', answer: '支持,跟随系统或手动切换。' }]}/>模式二:插槽模式(用 FAQItem 包裹,答案可写完整 Markdown)
<FAQ><FAQItem question="如何安装依赖?"> 运行 `npm install` 即可,详见[快速开始](https://example.com)。</FAQItem><FAQItem question="支持深色模式吗?"> **支持**。组件已适配系统深色与手动切换。</FAQItem></FAQ>items模式:answer字段按 HTML 渲染(可写<code>、<a>等标签),适合结构化数据。- 插槽模式:
<FAQItem>的插槽内容按 Markdown 渲染(支持加粗、列表、链接、行内代码),写起来更自然。
4.8 LinkButton — 链接按钮
参考 Starlight 的链接按钮,4 种样式、3 种尺寸,可选图标。
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
href | string | 必填 | 链接地址 |
variant | 'primary' | 'secondary' | 'minimal' | 'inline' | 'primary' | 按钮样式 |
size | 'sm' | 'md' | 'lg' | 'md' | 尺寸 |
icon | string | '' | 图标名称(见下方说明) |
iconPlacement | 'start' | 'end' | 'end' | 图标位置(前 / 后) |
target | string | — | 如 _blank;省略且 target="_blank" 时自动加 rel="noopener noreferrer" |
rel | string | — | 链接 rel |
class | string | '' | 附加 class |
示例
<LinkButton href="https://example.com" variant="primary">主要按钮</LinkButton><LinkButton href="https://example.com" variant="secondary">次要按钮</LinkButton><LinkButton href="https://example.com" variant="minimal">极简按钮</LinkButton><LinkButton href="https://example.com" variant="inline" size="sm">内联小按钮</LinkButton>关于 icon 属性(重要说明)
icon 属性接收 src/config/icons.json 中的图标键名(Heroicons 风格,如 arrow-right、download、external-link、github 等)。组件内部以 iconsConfig[icon] 方式查找。
src/config/icons.json 当前按 { outline: {...}, solid: {...} } 两级结构存放图标,而 LinkButton 直接以顶级键查找(iconsConfig[icon])。因此,若直接传 icon="arrow-right" 可能不会显示图标——你需要确保该键存在于 icons.json 顶级,或将 LinkButton 改为 iconsConfig.outline[icon] ?? iconsConfig.solid[icon]。文档按组件接口如实记录该属性;如需要可用的图标按钮,可先让图标键扁平化,或在此处传入完整 SVG 字符串(通过自定义组件包装)。
4.9 References — 参考资料
按 GB/T 7714 标准格式自动生成参考文献列表,支持折叠与计数。
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
title | string | '参考资料' | 区块标题 |
items | ReferenceItem[] | 必填 | 文献数组 |
collapsible | boolean | true | 是否可折叠 |
collapsed | boolean | false | 默认是否收起 |
ReferenceItem 字段:title(题名,必填)、author、type、source、date、url、accessDate、version、place、pages、volume、issue、description。
type 支持:M(专著) / J(期刊) / D(学位论文) / EB/OL(电子资源) / N(报纸) / C(论文集) / R(报告) / S / A / P / L。其中 M/J/D/EB-OL/N/C/R 有专门排版,S/A/P/L 与省略 type 走兜底格式。
示例
<References items={[{ type: 'M', author: '谢希仁', title: '计算机网络', version: '第8版', place: '北京', source: '电子工业出版社', date: '2021'},{ type: 'J', author: '李某, 王某', title: 'SDN 研究综述', source: '计算机学报', date: '2022', volume: '45', issue: '3', pages: '512-530'},{ type: 'EB/OL', author: 'Astro', title: 'Astro Documentation', date: '2026', accessDate: '2026-07-17', url: 'https://docs.astro.build'}]} />4.10 ComparisonTable — 对比表格
特性对比表,第一列自动加 feature-name 样式;单元格传入数组时渲染状态标签(含 ✅ 显绿色、❌ 显红色)。
属性
| 属性 | 类型 | 说明 |
|---|---|---|
headers | string[] | 表头数组 |
rows | (string | string[])[][] | 行数组;每行的每个单元格是字符串,或字符串数组(渲染为状态标签) |
示例
<ComparisonTableheaders={['特性', 'EVE-NG', 'GNS3', 'CML']}rows={[ ['开源免费', ['✅ 社区版'], ['✅'], ['❌']], ['图形界面', '有', '有', '有'], ['支持厂商', '多', '多', 'Cisco 为主']]}/>单元格值写成数组 ['✅ 支持'] 或 ['❌ 不支持'] 时,会渲染成圆角状态标签:包含 ✅ 为绿色 yes,包含 ❌ 为红色 no。普通字符串则原样显示。
4.11 Copyright — 版权声明
文章末尾标准化版权声明区块,右侧带品牌色渐变装饰条。
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
owner | string | 'ICT学习客栈' | 版权所有者 |
website | string | 'https://www.ictstu.com' | 网站链接 |
title | string | — | 文章标题 |
author | string | — | 作者 |
link | string | — | 文章链接 |
statement | string | — | 自定义声明(省略则使用许可证声明) |
license | string | 'CC BY-NC-ND 4.0' | 许可证名称 |
licenseUrl | string | CC 官网链接 | 许可证链接 |
组件还提供底部插槽(<slot/>),可补充额外声明文字。
示例
<Copyrighttitle="EVE-NG 安装与使用手册"author="ICT学习客栈"link="https://www.ictstu.com/eve-ng"license="CC BY-NC-ND 4.0">本文档仅供学习交流,禁止用于商业用途。</Copyright>4.12 Timeline — 时间轴
竖向时间轴,每个节点带圆点标记与日期。
属性
| 属性 | 类型 | 说明 |
|---|---|---|
items | { date: string; title?: string; content: string }[] | 时间轴节点数组 |
示例
<Timeline items={[{ date: '2024-01', title: '项目启动', content: '确定技术栈为 Astro + MDX。' },{ date: '2024-06', content: '完成首批网络实验文档。' },{ date: '2025-03', content: '上线组件库与本站手册。' }]} />4.13 ImageSearch — EVE-NG 镜像查询
供 EVE-NG 相关文章使用的镜像名称搜索组件,支持按名称模糊搜索、按 IOL / QEMU 筛选。
属性
| 属性 | 类型 | 说明 |
|---|---|---|
iolImages | string[] | IOL 镜像名称列表 |
qemuImages | string[] | QEMU 镜像名称列表 |
示例
<ImageSearchiolImages={['L2-ADVENTERPRISEK9-M', 'L3-ADVENTERPRISEK9-M']}qemuImages={['vEOS-4.28.0.qemu', 'vSRX-22.4.qemu']}/>镜像列表通常较长,建议集中在文章顶部或专门的“镜像清单”小节放置一次 ImageSearch,读者可搜索筛选;不要在多篇文章里重复粘贴同一长列表。
4.14 Announcement — 站点公告
滚动公告条 + 弹窗,配置来自 src/config/announcements.json,组件本身 无需传属性。
配置文件结构(关键字段):
{"global": { "enabled": true },"popup": { "enabled": true, "title": "站点公告", "content": "欢迎访问 ICT学习客栈!", "buttonText": "知道了", "expireDate": "2026-12-31"},"scrolling": { "enabled": true, "speed": 60, "items": [ { "text": "新教程上线", "link": "https://..." } ]},"pages": { "/eve-ng/intro": { "popup": { "enabled": true, "customTitle": "EVE-NG 专题", "customContent": "..." } }}}使用方式
<Announcement />- 弹窗 24 小时内对同一访客只显示一次(基于
localStorage)。 - 支持全局配置与按页面路径(
pages键为路由路径)覆盖;页面未匹配时回退到全局配置。 - 滚动公告在内容不溢出时居中静止,溢出时无缝滚动。
4.15 Categories — 技术栏目
首页技术栏目卡片网格,配置来自 src/config/categories.json,组件本身 无需传属性。
配置文件结构:
{"title": "技术栏目","subtitle": "按方向浏览教程","items": [ { "title": "网络技术", "description": "华为/eve-ng/网络实验", "link": "/network", "iconColor": "#3b82f6", "iconSvg": "<path d='...'/>" }]}使用方式
<Categories />iconSvg 只需提供 <svg> 内部路径内容(如 <path d="..."/>),组件会包裹进 viewBox="0 0 24 24" 的 <svg> 中;iconColor 控制图标与悬停强调色。
五、组合示例
下面给出一个“步骤 + 提示 + 下载 + 参考”的典型组合,供直接套用:
import Callout from '@/components/Callout.astro';import StepCard from '@/components/StepCard.astro';import DownloadCard from '@/components/DownloadCard.astro';import References from '@/components/References.astro';<Callout type="tip" title="开始之前">请确保已安装 Node.js 18+。</Callout><StepCard title="安装步骤" type="success"><ol> <li>克隆仓库:<code>git clone https://...</code></li> <li>安装依赖:<code>npm install</code></li> <li>启动服务:<code>npm run dev</code></li></ol></StepCard><DownloadCard title="安装包" href="https://..." type="aliyun" size="120 MB" /><References items={[{ type: 'EB/OL', title: '官方文档', url: 'https://docs.astro.build', accessDate: '2026-07-17' }]} />六、编写约定速查
- 块代码一律用
CodeBlock,禁止 Markdown 围栏;内联代码可用反引号。 - 每篇文章建议至少包含:正文 + 适当的
Callout+ 末尾Copyright。 - 组件属性中数组 / 对象 / 数字 / 布尔值必须包花括号
{}。 - 提示框优先用
:::type[标题]指令写法,复杂内容用<Callout>组件写法。 - 配色跟随
--brand-color与栏目主题,不要硬编码颜色(除非刻意定制)。 - 所有组件已适配深色模式,无需额外处理。