MDX 正文组件示例

MDX 允许在 Markdown 里直接写 Astro 组件。为了让正文保持干净，主题把常用的内容组件注册到了 MDX 渲染器里，写文章时不需要在顶部 import。本文逐项演示它们，代码可以直接复制到自己的文章里。

提示块

Aside 有四种语气，分别使用不同的颜色角色和图标：

标题可以省略；省略时只显示图标和正文，留给阅读流更轻的提示。

Aside 是 MDX 组件，而 Sätteri 的 Markdown callout 语法（> [!note]）仍然可用。两种写法可以在同一篇文章里共存：用 Markdown 写法写普通段落中的提示，用 Aside 在组件结构里嵌套提示。

徽标与按键

Badge 用来做行内标记，支持五种色调：neutral、primary、secondary、tertiary 和 error。也可以带图标，例如 已验证。

快捷键用 Kbd 表示：按 Ctrl + K 打开搜索，按 Shift + Enter 提交。多个按键并排书写即可，不需要额外的分隔符。

卡片

CardGrid 负责网格布局，LinkCard 负责单个链接。默认两列，窄屏自动变成一列；cols={3} 可以在宽屏上排三列。外部链接会自动带上箭头和新标签页属性。

步骤

Steps 用 CSS 计数器自动编号，插入或删除步骤都不需要改序号。每个 Step 可以带标题，也可以只放正文。

1. 安装依赖

   pnpm install

2. 启动开发服务器

   pnpm dev

   保存文章后页面会自动刷新。

3. 构建并预览

   pnpm build
   pnpm preview

   build 会先做类型检查，再生成静态文件并用 Pagefind 建立索引。

标签页

Tabs 适合并排展示互斥的内容，例如不同包管理器的命令。没有 JavaScript 时，所有面板会依次展开并保留标签，内容不会丢失；脚本加载后才会合并成真正的标签页。

pnpm add astro

npm install astro

yarn add astro

设置 defaultActive={1} 可以让第二个面板默认打开。标签页内部也可以嵌套其他组件，例如下面这个提示：

时间线

Timeline 按时间顺序排列事件，TimelineItem 的 date 会显示在条目标题上方。下面的日期只是演示数据。

1. 2026-10

   整理 MDX 组件

   把文章里反复出现的提示、步骤和卡片抽成组件，并通过 mdxComponents 注册。

2. 2026-09

   迁移到 Astro 7

   换用 Sätteri 处理 Markdown，代码块交给 Expressive Code。

3. 2026-08

   确定设计语言

   采用 Material Design 3 的色彩角色、排版等级和形状体系。

目录树

FileTree 接收一个 tree 模板字符串，原样保留缩进和制表符号，适合展示项目结构。title 显示为顶部标题。

components/
├── mdx/           正文组件
│   ├── Aside.astro
│   ├── Tabs.astro
│   └── index.ts
├── ui/            通用界面组件
content/
├── pages/
└── posts/

图片与视频

Figure 是带说明文字的图片。路径可以直接写 public/ 下的地址，或完整的 URL。

Video 接收视频平台的 iframe 地址，按 16 / 9 等比缩放；也可以用 ratio 覆盖比例。

行内图标

需要单个图标时，可以直接使用 Icon。图标名来自 Iconify，例如 、 和 。在配置里新增图标时，记得同步更新 astro.config.ts 的 include 列表。

组合使用

这些组件通常混在一起用。下面把提示、步骤和卡片放进同一段内容里：

1. 先写正文

   段落、列表和代码块已经能表达大部分内容。

2. 再挑组件

   并列链接用 CardGrid，有先后顺序用 Steps，互斥内容用 Tabs。

3. 最后检查窄屏

   卡片和标签页在手机上会重新排列，发布前记得缩窄窗口看一眼。