本文展示当前可用的四种风格提醒框、GitHub 仓库卡片、Bilibili / YouTube 视频卡片和正文图片预览。图片画廊与作品集仍在计划中。
下文区分已提供的功能与后续计划；已提供的组件包含可复制源码和实际效果。
功能状态
| 功能 | 当前状态 | 当前可用写法 |
|---|---|---|
| 多风格提醒框 | 已实现 | ::alert{type="note" theme="github"}，下一行用 :: 闭合 |
| 图片画廊 / 作品集 | 计划加入 | 单张图片、说明文字与普通链接 |
| GitHub 仓库卡片 | 已实现 | ::github{repo="owner/name"}，下一行用 :: 闭合 |
| Bilibili / YouTube 视频卡片 | 已实现 | 视频卡片教程与效果 |
基础表格、任务列表和删除线已经可用，详见 Markdown 教程。MDC 的组件写法与代码组接入条件见 MDC 教程。
多风格提醒框
提醒框用于呈现补充说明、操作建议和需要注意的事项。实现参考 Firefly 使用的 rehype-callouts 2.2.0，沿用其四种主题的颜色、图标与默认标题，并接入本站 MDC 和折叠组件。
参数与默认风格
::alert{type="warning" theme="github" title="版本兼容提醒"}
升级前请阅读 **迁移说明**。
::
| 参数 | 说明 | 默认值 |
|---|---|---|
type | 当前风格支持的提醒类型，不区分大小写 | note |
theme | github、obsidian、vitepress、docusaurus | 站点配置 |
title | 纯文本标题，省略或留空时使用类型的默认标题 | 随类型与风格变化 |
collapsible | 是否允许展开与收起 | false |
open | 可折叠提醒框的初始展开状态 | false |
在 apps/website/app/app.config.ts 的 site.article 中配置全站默认风格，保留同级的 notices 配置：
alerts: { theme: 'github' }
单个提醒框的 theme 优先于站点默认。无效主题回退到站点默认，站点配置也无效时使用 GitHub；无效或当前风格不支持的 type 回退到 note。切换全站风格前，请核对类型表，或为使用特定类型的提醒框显式填写 theme。
本站只提供 ::alert MDC 写法，普通 > 引用 保持原样；> [!NOTE]、:::note 和 Python-Markdown 的 !!! 不会转换成提醒框。内容组件必须使用结束标记 ::。
GitHub 风格
彩色左边线与标题区分五类信息，正文背景保持透明。
源码
::alert{theme="github" type="note"}
未指定标题时显示默认类型名。
::
::alert{theme="github" type="tip"}
把重复步骤写成脚本，可以减少手动操作。
::
::alert{theme="github" type="important" title="先填写必填信息"}
每篇文章都需要 title、description 和 publish。
::
::alert{theme="github" type="warning"}
升级依赖前请检查版本兼容性。
::
::alert{theme="github" type="caution"}
覆盖文件前请保留原始副本。
::
效果
未指定标题时显示默认类型名。
把重复步骤写成脚本，可以减少手动操作。
每篇文章都需要 title、description 和 publish。
升级依赖前请检查版本兼容性。
覆盖文件前请保留原始副本。
Obsidian 风格
使用淡色背景和彩色标题。支持全部 27 种类型；同组类型共享外观，但保留各自默认标题，例如 check 显示 Check。
| 类型 | 用途 |
|---|---|
note | 笔记 |
abstract、summary、tldr | 摘要与总结 |
info、todo | 信息与待办 |
tip、hint、important | 技巧与重要提示 |
success、check、done | 成功、检查与完成 |
question、help、faq | 问题与帮助 |
warning、attention、caution | 警告与注意 |
failure、missing、fail | 失败与缺失 |
danger、error、bug | 危险、错误与缺陷 |
example | 示例 |
quote、cite | 引文 |
源码
::alert{theme="obsidian" type="check"}
检查已通过，可以继续下一步。
::
::alert{theme="obsidian" type="tip" title="操作建议"}
建议将检查命令加入提交前流程。
::
效果
检查已通过，可以继续下一步。
建议将检查命令加入提交前流程。
VitePress 风格
圆角色块，默认标题使用大写。支持 note、tip、important、warning、caution。
源码
::alert{theme="vitepress" type="tip"}
提醒框内可以使用 **强调**、`行内代码` 和[普通链接](/about)。
::
效果
提醒框内可以使用 强调、行内代码 和普通链接。
Docusaurus 风格
彩色左边线搭配背景色，正文与标题采用对应前景色。支持 note、tip、info、warning、danger。
源码
::alert{theme="docusaurus" type="danger" title="覆盖前先备份"}
此操作会替换现有文件，请确认备份可以恢复。
::
效果
此操作会替换现有文件，请确认备份可以恢复。
折叠、代码与嵌套
添加 collapsible 后默认收起，使用 :open="true" 设置初始展开。字符串 open="false" 和绑定 :open="false" 均表示收起。Tab 可聚焦标题按钮，Enter 或空格切换状态；目录或锚点跳转到隐藏标题时会展开其父级提醒框。
外层组件使用更多冒号即可嵌套，不同风格可以在同一篇文章中混用。
源码
:::alert{theme="github" type="warning" title="发布检查" collapsible :open="true"}
- 确认文章元数据完整。
- 执行检查与测试。
```sh
vp run check
vp run -r test
```
::alert{theme="docusaurus" type="info" title="补充说明" collapsible}
#### 检查命令说明
检查通过后再进入发布流程。
::
:::
效果
以上内容结束后，正文继续正常排版。可以通过检查命令说明验证隐藏标题的定位。
图片画廊与作品集
图片画廊适合把同一主题的多张图片放在一起浏览；作品集则需要在图片之外提供作品名称、说明和访问链接。
内容准备
准备图片时，建议同时整理以下信息，便于后续迁移到组件中：
- 图片地址：优先使用本站
/images/下的资源。 - 替代文本：描述画面中的实际内容。
- 图注：补充图片背景、版本或拍摄信息。
- 作品名称与简介：说明作品是什么、用于什么场景。
- 访问地址：需要跳转到作品页面时填写。
当前写法
先用标准图片语法展示单张图片，再用正文补充图注和链接。
源码
**作品名称：文章内容处理示意**
这张示意图说明 Markdown 文件经过内容解析后显示为文章页面的过程。
[阅读对应教程](/posts/markdown/markdown)
效果
作品名称：文章内容处理示意
这张示意图说明 Markdown 文件经过内容解析后显示为文章页面的过程。
当前正文单图已支持亚克力预览、1–4 倍缩放、拖拽和触摸操作；连续插图仍按正文顺序显示。网格排版、前后切图和作品卡片尚未提供。图片参数与操作见 MDC 教程。
GitHub 仓库卡片
卡片布局参考 Firefly 仓库卡片，配色使用当前文章主题。顶部显示头像与仓库名称，底部显示 Star、Fork、许可证和主要语言。
写法与效果
repo 是必填参数，只接受静态的公开仓库标识 owner/name，不接受完整 URL。卡片不接收正文内容，必须写结束标记，否则会把后续段落收进组件并触发内容校验错误。
源码
::github{repo="setobox/mukuchi"}
::
效果
setobox/mukuchiBlog.00MITTypeScript在新标签页打开 GitHub 仓库数据如何更新
仓库数据在每次生产构建时从 GitHub 获取，形成随站点发布的快照。页面首屏已有仓库信息，阅读时不请求 GitHub API。统计采用紧凑格式，悬停或使用辅助技术可读取完整计数。
GitHub 超时、限流、仓库不可访问或返回无效数据时，构建继续，未取得的字段显示 -；实际零值显示 0。仓库名称与链接保留，下一次成功构建会更新数据。未配置简介、许可证或主要语言的字段也显示 -。
开发服务启动时获取快照，新增仓库引用会补取；已知仓库在同一开发会话中复用，重启服务可刷新。文章与关于页均可使用。普通仓库链接保持原样：
后续文档
图片画廊与作品集将在后续步骤实现；当前可以使用提醒框、普通引用、正文图片和仓库卡片。
文章自身的 wip: true 会在标题信息后自动显示施工提醒，不会隐藏文章。维护日期距当前满 365 天时另行显示内容时效提醒；这些自动状态提醒与正文中的通用提醒框独立。