一、如何使用组件

站点所有文章均使用 MDX 编写。在任意 .mdx 文件顶部通过 import 引入组件后即可像普通 HTML 标签一样使用:

CODEmarkdown
import CodeBlock from '@/components/CodeBlock.astro';<CodeBlock type="terminal" code={`ls -la`} />

要点:

  • 路径别名 @/ 等价于项目根目录的 src/,即 @/components/CodeBlock.astro 指向 src/components/CodeBlock.astro
  • 组件既可以自闭合 <CodeBlock />(属性写在标签内),也可以成对 <Callout>...</Callout>(内容写在标签之间,即“插槽 / slot”)。需要正文内容的组件(如 CalloutStepCardFAQ 的插槽模式)必须用成对写法。
  • 组件属性值分为两类:字符串(直接写 title="提示")与表达式(用花括号包裹,如 items={[{question:'...', answer:'...'}]})。数组、对象、数字、布尔值必须加花括号。
  • 所有内置组件均已适配深色模式,无需额外处理。
块级代码必须用 CodeBlock 组件

本站约定:禁止使用 Markdown 原生围栏代码块(三个反引号)。所有块级代码一律用 <CodeBlock> 组件渲染。原因见 src/styles/global.css 第五部分注释——Markdown 围栏块会被渲染成 <pre><code> 后套用行内代码样式,导致视觉异常。内联代码(行内 code)仍可用单个反引号。

二、组件一览

组件文件主要用途
CodeBlockCodeBlock.astro5 种差异化代码块(代码 / 终端 / 网络 / 配置 / 日志)
CalloutCallout.astro备注、提示、警告等强调框(8 种类型),支持折叠
StepCardStepCard.astro带序号圆圈与连接线的操作步骤卡片
AuthorCardAuthorCard.astro文章作者信息卡片(头像、简介、社交链接、公众号二维码)
DownloadCardDownloadCard.astro下载链接卡片(内置 11 种网盘图标)
BilibiliPlayerBilibiliPlayer.astroB 站视频 16
响应式嵌入
FAQFAQ.astro折叠式常见问题,带搜索框;支持 items 与插槽两种模式
LinkButtonLinkButton.astro链接按钮(4 种样式、3 种尺寸、可选图标)
ReferencesReferences.astroGB/T 7714 标准参考文献列表
ComparisonTableComparisonTable.astro特性对比表,支持 ✅/❌ 状态标签
CopyrightCopyright.astro文章末尾版权声明区块
TimelineTimeline.astro时间轴
ImageSearchImageSearch.astroEVE-NG 镜像名称搜索(IOL / QEMU 筛选)
AnnouncementAnnouncement.astro站点公告(滚动条 + 弹窗),配置来自 announcements.json
CategoriesCategories.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 字段控制;CalloutTimelineLinkButtonAuthorCard 等组件会读取 --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

示例:用栅格并排两个下载卡片。

CODEmarkdown
<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-mode class
  • 给祖先元素加 data-theme="dark" 属性

3.4 Callout 指令语法(免 import 速记)

<Callout> 组件写法外,正文里还可用 remark-directive 语法直接写提示框,无需 import

CODEmarkdown
:::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'必填代码块类型,决定配色与高亮逻辑
codestring必填代码文本内容
langstring语言标识,仅 type="code" 时用(如 pythongojson
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 有效,标签栏显示级别名
filePathstringconfig 有效,显示配置文件路径并按后缀推断高亮语言
labelstring额外标签(如中间件名),config 下常配合 filePath
titlestring覆盖默认标签文字(CODE/TERMINAL/NETWORK/CONFIG/LOG)

各类型说明与示例

type="code" — 编程语言,蓝色主题,Shiki 多语言高亮:

CODEmarkdown
<CodeBlock type="code" lang="python" code={`import osprint(os.getcwd())`} />

type="terminal" — 终端交互,绿色主题,自动区分 $/#/> 提示符与输出,复制时剥离提示符:

CODEmarkdown
<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# 等设备前缀:

CODEmarkdown
<CodeBlock type="network" vendor="huawei" code={`interface GigabitEthernet0/0ip address 192.168.1.1 255.255.255.0no shutdown`} />

type="config" — 配置文件,紫色主题,支持 filePathlabel

CODEmarkdown
<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 控制标签:

CODEmarkdown
<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'类型,决定配色与默认标题
titlestring类型默认标题自定义标题
iconstring类型默认图标自定义 SVG 图标(直接传 SVG 字符串)
collapsiblebooleanfalse是否可折叠
collapsedbooleanfalse折叠时是否默认收起(需 collapsible
dismissiblebooleanfalse预留:是否可关闭
idstring自动生成元素 id(一般无需指定)

8 种类型对照

类型默认标题配色
note备注
tip提示绿
info信息
warning注意
danger危险
success成功绿
question问题
example示例靛蓝

组件写法示例

CODEmarkdown
<Callout type="tip" title="小技巧">这里写正文,支持 **Markdown**、行内 `code` 与[链接](https://example.com)。</Callout><Callout type="danger" collapsible collapsed title="排错清单">点击标题可展开。</Callout>

指令写法(见 3.4 节)更简洁,正文里推荐用指令写法。


4.3 StepCard — 步骤卡片

展示操作步骤或流程,序号为圆圈 + 虚线连接线,最后一步显示 ✓。内容通过插槽传入,通常用有序列表 <ol>

属性

属性类型默认值说明
titlestring''卡片标题(可选,显示在顶部带下划线区)
iconstring''标题前的 SVG 图标字符串(可选)
size'sm' | 'md' | 'lg''md'序号圆圈尺寸
type'default' | 'success' | 'warning' | 'info''default'配色类型(default 跟随品牌色)

示例

CODEmarkdown
<StepCard title="初始化配置" type="success"><ol>  <li>打开终端,进入项目目录。</li>  <li>执行 <code>npm install</code> 安装依赖。</li>  <li>运行 <code>npm run dev</code> 启动本地服务。</li></ol></StepCard>
关于 size / type

size 控制圆圈大小(sm 1.5rem / md 1.75rem / lg 2rem);type 控制整体配色(默认跟随品牌蓝,另可选绿/黄/青)。组件内部会自动把 <ol> 渲染成带圆圈序号的步骤,把 <ul> 渲染成同色系小圆点列表。


4.4 AuthorCard — 作者卡片

展示文章作者信息,支持头像、简介、社交链接、博客与公众号二维码弹窗。

属性

属性类型说明
namestring作者姓名(必填)
rolestring职务 / 头衔
avatarstring头像图片 URL
avatarUrlstring点击头像跳转的链接(有则头像可点击)
biostring作者简介
links{ label: string; url: string }[]自定义链接列表
blogUrlstring博客地址(显示“博客”按钮)
wechatQrCodestring公众号二维码图片 URL(显示“微信公众号”按钮,点击弹出)

示例

CODEmarkdown
<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 图标,按钮默认新窗口打开。

属性

属性类型默认值说明
titlestring必填文件 / 资源标题
hrefstring必填下载地址(新窗口打开)
descriptionstring''描述
sizestring''文件大小,如 1.2 GB
versionstring''版本号,如 2.3
btnTextstring'前往下载'按钮文字
type见下'baidu'网盘类型,决定左侧图标
tagstring''标题后的小标签(如“官方”“VIP”)

type 可选值(共 11 种):baidu / widely / tiandun / lanzou / aliyun / chengtong / pan123 / hi168 / guanwang / quark / xunlei

示例

CODEmarkdown
<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 站播放器。

属性

属性类型默认值说明
bvidstring''B 站 BV 号,如 BV1kj59zGEqV
aidstring''视频 av 号(与 bvid 二选一)
pnumber1分 P 编号
cidstring''视频 CID(可选)
autoplaybooleanfalse是否自动播放

示例

CODEmarkdown
<BilibiliPlayer bvid="BV1kj59zGEqV" p={2} />
注意

两个必填其一:bvidaid。若都不传,组件会渲染占位提示“请传入 bvid 或 aid 参数”。


4.7 FAQ — 常见问题

折叠式问答列表,顶部带搜索框(按问题文本过滤),支持两种数据模式。

属性

属性类型默认值说明
items{ question: string; answer: string }[]数据模式:直接传问答数组
collapsiblebooleantrue是否允许点击展开/收起

模式一:items 数据模式(answer 支持 HTML)

CODEmarkdown
<FAQitems={[  { question: '如何安装依赖?', answer: '运行 <code>npm install</code> 即可。' },  { question: '支持深色模式吗?', answer: '支持,跟随系统或手动切换。' }]}/>

模式二:插槽模式(用 FAQItem 包裹,答案可写完整 Markdown)

CODEmarkdown
<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 种尺寸,可选图标。

属性

属性类型默认值说明
hrefstring必填链接地址
variant'primary' | 'secondary' | 'minimal' | 'inline''primary'按钮样式
size'sm' | 'md' | 'lg''md'尺寸
iconstring''图标名称(见下方说明)
iconPlacement'start' | 'end''end'图标位置(前 / 后)
targetstring_blank;省略且 target="_blank" 时自动加 rel="noopener noreferrer"
relstring链接 rel
classstring''附加 class

示例

CODEmarkdown
<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-rightdownloadexternal-linkgithub 等)。组件内部以 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 标准格式自动生成参考文献列表,支持折叠与计数。

属性

属性类型默认值说明
titlestring'参考资料'区块标题
itemsReferenceItem[]必填文献数组
collapsiblebooleantrue是否可折叠
collapsedbooleanfalse默认是否收起

ReferenceItem 字段:title(题名,必填)、authortypesourcedateurlaccessDateversionplacepagesvolumeissuedescription

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 走兜底格式。

示例

CODEmarkdown
<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 样式;单元格传入数组时渲染状态标签(含 ✅ 显绿色、❌ 显红色)。

属性

属性类型说明
headersstring[]表头数组
rows(string | string[])[][]行数组;每行的每个单元格是字符串,或字符串数组(渲染为状态标签)

示例

CODEmarkdown
<ComparisonTableheaders={['特性', 'EVE-NG', 'GNS3', 'CML']}rows={[  ['开源免费', ['✅ 社区版'], ['✅'], ['❌']],  ['图形界面', '有', '有', '有'],  ['支持厂商', '多', '多', 'Cisco 为主']]}/>
状态标签规则

单元格值写成数组 ['✅ 支持']['❌ 不支持'] 时,会渲染成圆角状态标签:包含 ✅ 为绿色 yes,包含 ❌ 为红色 no。普通字符串则原样显示。


文章末尾标准化版权声明区块,右侧带品牌色渐变装饰条。

属性

属性类型默认值说明
ownerstring'ICT学习客栈'版权所有者
websitestring'https://www.ictstu.com'网站链接
titlestring文章标题
authorstring作者
linkstring文章链接
statementstring自定义声明(省略则使用许可证声明)
licensestring'CC BY-NC-ND 4.0'许可证名称
licenseUrlstringCC 官网链接许可证链接

组件还提供底部插槽(<slot/>),可补充额外声明文字。

示例

CODEmarkdown
<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 }[]时间轴节点数组

示例

CODEmarkdown
<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 筛选。

属性

属性类型说明
iolImagesstring[]IOL 镜像名称列表
qemuImagesstring[]QEMU 镜像名称列表

示例

CODEmarkdown
<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,组件本身 无需传属性

配置文件结构(关键字段):

CODEjson
{"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": "..." }  }}}

使用方式

CODEmarkdown
<Announcement />
行为说明
  • 弹窗 24 小时内对同一访客只显示一次(基于 localStorage)。
  • 支持全局配置与按页面路径(pages 键为路由路径)覆盖;页面未匹配时回退到全局配置。
  • 滚动公告在内容不溢出时居中静止,溢出时无缝滚动。

4.15 Categories — 技术栏目

首页技术栏目卡片网格,配置来自 src/config/categories.json,组件本身 无需传属性

配置文件结构:

CODEjson
{"title": "技术栏目","subtitle": "按方向浏览教程","items": [  {    "title": "网络技术",    "description": "华为/eve-ng/网络实验",    "link": "/network",    "iconColor": "#3b82f6",    "iconSvg": "<path d='...'/>"  }]}

使用方式

CODEmarkdown
<Categories />
iconSvg 说明

iconSvg 只需提供 <svg> 内部路径内容(如 <path d="..."/>),组件会包裹进 viewBox="0 0 24 24"<svg> 中;iconColor 控制图标与悬停强调色。

五、组合示例

下面给出一个“步骤 + 提示 + 下载 + 参考”的典型组合,供直接套用:

CODEmarkdown
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 与栏目主题,不要硬编码颜色(除非刻意定制)。
  • 所有组件已适配深色模式,无需额外处理。