Ethereal 主题文章组件速查手册（27 种）
这是 Ethereal 主题 27 种文章组件的速查手册，底层统一由 content-widgets 插件渲染、主题自动适配二次元配色。组件分两种写法：7 种高频组件用 callout 短代码（> [!ethereal-xxx]，markdown 友好）；其余 20 种直接写 <xhhao-com-xxx> 标签。想要哪种效果，找到对应章节复制源码、改内容即可。
通用语法
写法一：callout 短代码（7 种高频）
> [!ethereal-类型]
> ### 第 1 节标题
> 第 1 节正文（支持 markdown）
>
> ### 第 2 节标题
> 第 2 节正文
写法二：直接写标签（20 种）
这是一段正文，中间夹一个 <xhhao-com-badge type="info">徽标</xhhao-com-badge> 标签。
⚠️ 标签组件的内容只认 HTML，不认 markdown——块级 HTML 里的
**加粗**不会被渲染，要用<strong>加粗</strong>或纯文本。行内标签嵌在段落里时，周围文字照常走 markdown。
一、callout 短代码（7 种）
| 短代码 | 类型名 | 作用 | 每节标题格式 |
|---|---|---|---|
| 标签页 | tab | 多选项点击切换 | ### 标签名 |
| 折叠面板 | collapse | 手风琴 FAQ | ### 标题 |
| 时间线 | timeline | 演进历程 | ### 时间 | 标题 |
| 步骤 | steps | 操作流程 | ### 标题（序号自动） |
| 进度条 | progress | 熟练度 / 进度 | ### 百分比 | 标签 |
| 对话气泡 | chat | 聊天记录 | ### [self|system]名字 |
| 多栏卡片 | columns | 并列对比 | ### 列标题 |
tab 标签页
亮色模式
白底卡片，适合白天阅读，文字对比度高。
暗色模式
深色 glassmorphism 配青色渐变，晚上不刺眼。
跟随系统
根据系统外观自动切换，最省心。
> [!ethereal-tab]
> ### 亮色模式
> 白底卡片，适合白天阅读，文字对比度高。
>
> ### 暗色模式
> 深色 glassmorphism 配青色渐变，晚上不刺眼。
>
> ### 跟随系统
> 根据系统外观自动切换，最省心。
collapse 折叠面板
短代码写在哪？
直接写进文章 markdown 正文即可，编辑器里选「Markdown」模式粘贴。
正文能用列表吗？
可以。折叠体走正常 markdown 渲染，列表、加粗、链接、行内代码都支持。
> [!ethereal-collapse]
> ### 短代码写在哪？
> 直接写进文章 markdown 正文即可。
>
> ### 正文能用列表吗？
> 可以，折叠体走正常 markdown 渲染。
timeline 时间线
2026-08 | 初版
引入文章短代码能力，首批支持 tab / collapse / timeline。
2026-09 | 转译复用
底层改用 content-widgets 插件渲染，扩充到 27 种组件。
> [!ethereal-timeline]
> ### 2026-08 | 初版
> 引入文章短代码能力。
>
> ### 2026-09 | 转译复用
> 底层改用插件渲染，扩充到 27 种组件。
steps 步骤
打开文章编辑器
进入 Halo 后台，打开或新建一篇文章。
粘贴短代码块
把对应的 callout 块粘贴进正文。
预览确认效果
前台打开文章，确认组件渲染正常。
> [!ethereal-steps]
> ### 打开文章编辑器
> 进入 Halo 后台，打开或新建一篇文章。
>
> ### 粘贴短代码块
> 把对应的 callout 块粘贴进正文。
>
> ### 预览确认效果
> 前台打开文章，确认组件渲染正常。
progress 进度条
90 | 前端
75 | 后端
60 | 运维
> [!ethereal-progress]
> ### 90 | 前端
>
> ### 75 | 后端
>
> ### 60 | 运维
chat 对话气泡
[system]系统提示
欢迎来到 Ethereal，文章组件已就绪。
[self]我
帮我把这段对话渲染成气泡。
小沃
没问题，用 ethereal-chat 即可。
> [!ethereal-chat]
> ### [system]系统提示
> 欢迎来到 Ethereal。
>
> ### [self]我
> 帮我把这段对话渲染成气泡。
>
> ### 小沃
> 没问题，用 ethereal-chat 即可。
columns 多栏卡片
项目介绍文
用 timeline 讲演进、用 columns 摆场景、用 tab 展示多形态。
教程类文章
用 steps 拆步骤、用 collapse 收 FAQ、用 progress 列进度。
> [!ethereal-columns]
> ### 项目介绍文
> 用 timeline 讲演进、用 columns 摆场景。
>
> ### 教程类文章
> 用 steps 拆步骤、用 collapse 收 FAQ。
二、直接标签组件（20 种）
提示类
alert 提示框（type：tip / info / question / warning / error）
<xhhao-com-alert type="warning" title="注意">
这里写警告内容，支持 <strong>HTML</strong>。
</xhhao-com-alert>
note 便签（color：yellow / green / blue / pink / purple）
<xhhao-com-note color="yellow">这是黄色便签，记一条重点。</xhhao-com-note>
result 结果（type：success / info / warning / error）
<xhhao-com-result type="success" title="部署完成">站点已上线，访问正常。</xhhao-com-result>
quote 引用
<xhhao-com-quote>保持清醒，保持热爱。</xhhao-com-quote>
布局类
card-list 卡片列表
- 卡片一：内容 A
- 卡片二：内容 B
- 卡片三：内容 C
<xhhao-com-card-list>
<ul>
<li>卡片一：内容 A</li>
<li>卡片二：内容 B</li>
<li>卡片三：内容 C</li>
</ul>
</xhhao-com-card-list>
compare 对比
<xhhao-com-compare left-title="之前" right-title="之后">
<div>手写 HTML 标签，编辑器里看不到效果。</div>
<div>callout 短代码，markdown 直接写。</div>
</xhhao-com-compare>
代码类
copy 复制命令
<xhhao-com-copy prompt="$">pnpm install</xhhao-com-copy>
command-group 命令组
<xhhao-com-command-group title="部署命令">
<xhhao-com-command prompt="$">pnpm install</xhhao-com-command>
<xhhao-com-command prompt="$">pnpm build</xhhao-com-command>
</xhhao-com-command-group>
key 快捷键
按
按 <xhhao-com-key code="K" cmd></xhhao-com-key> 打开搜索。
展示类
pic 图片（src / caption）
<xhhao-com-pic src="https://picsum.photos/960/400" caption="图片说明文字"></xhhao-com-pic>
pdf 文档预览（src / title，可选 width / height）
<xhhao-com-pdf src="https://example.com/sample.pdf" title="示例文档"></xhhao-com-pdf>
button 按钮（type：primary / secondary / ghost）
<xhhao-com-button href="https://example.com" type="primary">访问站点</xhhao-com-button>
task-list 任务清单
<xhhao-com-task-list>
<xhhao-com-task checked>完成的任务</xhhao-com-task>
<xhhao-com-task>待办事项</xhhao-com-task>
</xhhao-com-task-list>
行内类
badge 徽标（type：default / info / success / warning / error）
这是
这是 <xhhao-com-badge type="info">新功能</xhhao-com-badge> 徽标。
status 状态（label + value）
服务状态：
服务状态：<xhhao-com-status label="数据库" value="运行中" type="success"></xhhao-com-status>
blur 模糊防剧透（hover 显示）
下集预告：
下集预告：<xhhao-com-blur>主角其实是大反派</xhhao-com-blur>
annotation 批注（note 为悬浮批注）
这里有个
这里有个<xhhao-com-annotation note="这是补充说明">专业术语</xhhao-com-annotation>。
tip 悬浮提示（tip 为悬浮内容）
把鼠标悬停在
把鼠标悬停在<xhhao-com-tip tip="这里是提示内容">这段文字</xhhao-com-tip>上。
emoji-clock 表情时钟（动态跟随时间）
现在时间：
现在时间：<xhhao-com-emoji-clock></xhhao-com-emoji-clock>
reading-time 阅读时间（主题自动统计字数，写空标签即可，无需手动填 words）
本文
本文 <xhhao-com-reading-time></xhhao-com-reading-time>。
注意事项
- 主题版本：需 Ethereal 主题 1.3.99+ 且已启用 content-widgets 插件（≥ v1.0.3），组件才会渲染；否则显示成普通引用卡片 / 裸标签。其中 PDF 预览（
xhhao-com-pdf）需插件 ≥ v1.0.3。 - 别用 fenced code 承载 callout 短代码：不要写成
```ethereal-tab代码块，编辑器会报Language not found；一律用> [!ethereal-tab]引用块。 - 标签内容只认 HTML：
<xhhao-com-*>标签内部用 HTML（<strong>、<ul><li>）而非 markdown 的**加粗**、- 列表。 - 节之间空一行：callout 短代码每个
###节之间加一个>空行，渲染最稳。 - progress 无正文：进度条短代码只写标题
百分比 | 标签，不要在后面加正文。