Frontmatter#

每篇文章都以 YAML frontmatter 开始。它定义了文章页面、列表、搜索结果和订阅源使用的元数据：

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
---

让 frontmatter 专注于元数据。导入和 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
:::

图片和说明文字#

图片替代文本为辅助技术描述图片。Markdown 标题会成为可见的说明文字，可选的 w-N% 标记用于控制宽度。

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

有效宽度范围是 w-1% 到 w-100%。如果图片应使用正常的响应式宽度，请省略该标记。

内部和外部链接#

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

• 使用相对站点 URL 访问 About 页面。
• 将其与外部参考进行比较。

内部内容请使用相对路径。https://example.com/ 等外部源会由主题单独归类。

编写可移植的 MDX#

文章页面、RSS 和 Atom 共享同一内容处理流程。交互式脚本会从订阅源中移除， 但组件、提示框、Wiki 链接、数学公式和代码组生成的语义化 HTML 仍然易于阅读。

为了获得可靠的输出：

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

MDX 最适合作为 Markdown 的扩展，而不是替代品。先从普通内容开始， 然后只在能让文章更清晰或更易复用的地方引入表达式和组件。