前置元数据#

每篇文章都以 YAML 前置元数据开头。它定义了文章页、列表、搜索结果和订阅源所用的元数据。 （用于文章页、列表、搜索结果与订阅源）：

1
---
2
title: My MDX Article
3
published: 2026-08-08
4
description: A short introduction shown in article previews.
5
tags: [Markdown, MDX]
6
category: Guides
7
draft: false
8
---

前置元数据应只放元数据。导入语句和 JavaScript 声明应紧接在结束分隔符 --- 之后。

标准 Markdown#

MDX 文章的大部分内容仍应是普通 Markdown。这样既能保持源码易读，也能为 RSS 和 Atom 阅读器提供可用的静态版本。

1
## A section heading
2

3
- A list item
4
- **Bold text** and *emphasis*
5
- [A normal link](https://example.com/)
6

7
> A blockquote remains a blockquote.

导入与使用组件#

MDX 可在顶层导入 Astro 组件，并在文档中直接使用。 组件名必须以大写字母开头。

1
import Notice from "../../components/Notice.astro";
2

3
export const message = "Props can come from an MDX expression.";
4

5
<Notice label={message} />

下面这个面板是本文渲染的一个真实组件：

用组件承载可复用的界面元素或有结构的内容；正文部分优先使用 Markdown，以保持文章的可移植性与可读性。

JavaScript 表达式#

顶层的 export const 声明可以为文档准备数据。 用花括号插入 JavaScript 表达式：

1
export const topics = ["components", "expressions", "extended Markdown"];
2

3
This guide covers {topics.length} topics: {topics.join(", ")}.

这个实时表达式统计出共 3 个主题：components，expressions，extended Markdown。

表达式在构建时应当是确定性的。像 window、document 这类仅浏览器可用的 API，应放在组件脚本里， 而非 MDX 模块体中。

提示框#

提示框可以在不编写自定义组件的情况下突出显示信息：

TIP

用最简单且能生效的语法

正文用 Markdown，小的动态值用 MDX 表达式， 需要复用标记或行为时才用组件。

1
:::tip[Optional title]
2
This content is emphasized as a tip.
3
:::

Wiki 链接#

行内 Wiki 链接指向另一篇文章，同时保持句子通顺。 例如，可继续阅读 内容指南。

独立的 Wiki 链接会渲染成一张文章卡片，包含其可用元数据和 封面图：

撰写博客文章

关于文章结构与 frontmatter 的通用示例。

2024-04-01指南#示例#写作#Markdown

1
Read [[guide|the content guide]] for more details.
2

3
[[guide]]

数学与化学公式#

行内公式用单个美元符号，展示公式用一对美元符号。 还可通过 mhchem 扩展书写化学记号。

爱因斯坦质能方程为 $E = mc^2$。

化学反应可写作 $\ce{H2O + CO2 -> H2CO3}$。

1
Inline: $E = mc^2$
2

3
Display: $$\int_0^1 x^2\,dx = \frac{1}{3}$$
4

5
Chemistry: $\ce{H2O + CO2 -> H2CO3}$

代码组#

当读者可在等价的示例之间切换时，使用代码组。 每个标签对应一个围栏代码块：

1
export const renderTarget = "page";

1
pnpm build

1
::: code-group labels=[TypeScript, Shell]
2

3
```ts
4
export const renderTarget = "page";
5
```
6

7
```bash
8
pnpm build
9
```
10

11
:::

图片与图注#

图片的 alt 文本用于向辅助技术描述图片。Markdown 的 title 会成为可见图注，可选的 w-N% 记号用于控制宽度。

1
![Descriptive alt text w-60%](./image.webp "Visible image caption")

有效宽度范围为 w-1% 到 w-100%。若图片应使用常规响应式宽度， 可省略该记号。

内部链接与外部链接#

使用已配置站点源站的相对链接和绝对 URL 会被归类为内部链接； 指向其他源站的链接则获得主题配置的 外链属性。

• 访问使用相对站点 URL 的关于页。
• 可将其与外部参考文档对比。

内部内容请使用相对路径。像 https://example.com/ 这样的外部源站会被主题单独归类。

编写可移植的 MDX#

文章页、RSS 和 Atom 共用同一套内容管线。交互脚本会在订阅源中被移除， 但由组件、提示框、Wiki 链接、公式、代码组和图片生成的 语义化 HTML 仍保持可读。

为保证输出可靠，请遵循：

1. 主要说明文字使用 Markdown。
2. 为图片提供有意义的 alt 文本，并让组件输出语义化 HTML。
3. 避免在顶层表达式中使用浏览器全局对象。
4. 确保客户端 JavaScript 运行之前，有用信息已经可见。
5. 发布前运行 pnpm test、pnpm check 和 pnpm build。

MDX 最好是作为 Markdown 的扩展，而非替代品。先从纯内容写起， 只在能让文章更清晰、更易复用的地方才引入表达式和 组件。