前言#

每篇文章都以 YAML 前言开头。它定义了文章页面、列表、搜索结果和提要使用的元数据：

1
---
2
title: My MDX Article
3
published: 2026-08-08
4
description: 文章预览中显示的简短介绍。
5
tags: [Markdown, MDX]
6
category: 指南
7
draft: false
8
---

让前言专注于元数据。导入和JavaScript声明应紧跟在结束---分隔符之后。

标准 Markdown#

MDX文章的大部分内容应该保持为普通的Markdown。这使得源代码易于阅读，并为RSS和Atom阅读器提供了一个有用的静态版本。

1
## 章节标题
2

3
- 列表项
4
- **粗体文本** 和 *强调*
5
- [正常链接](https://example.com/)
6

7

8
> 区块行情仍然是区块行情。

导入和使用组件#

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个主题：组件、表达式、扩展Markdown。

表达式在构建过程中应该是确定性的。仅限浏览器的API，如window和document，属于组件脚本内部，而不是MDX模块主体。

标注框#

标注突出显示信息，无需自定义组件：

TIP

使用最简单的语法

为散文选择Markdown，为小动态值选择MDX表达式，以及在需要重用标记或行为时选择组件。

1
:::tip[可选标题]
2
此内容被强调为提示。
3
:::

Wiki 链接#

内联Wiki链接指向另一篇文章，同时保持句子的可读性。例如：阅读 Blog简单指南 并了解更多详细信息.

一个独立的Wiki链接将成为一个包含可用元数据和封面图像的文章卡片：

简单指南

如何使用这个博客模板。

2024-04-01指南#Mizuki#Blogging

1
阅读 [[简单指南|Blog简单指南]] 并了解更多详细信息。
2

3
[[简单指南]]

数学与化学#

内联数学使用单美元符号，而显示方程使用一对。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
:::

图像和字幕#

Image alt-text描述了辅助技术的图像。Markdown标题变为可见标题，可选的w-N%标记控制宽度。

1
![描述性替代文本 w-60%](./image.webp "可见图像标题")

有效宽度范围为w-1%至w-100%。当图像应使用正常响应宽度时，省略标记。

内部和外部链接#

使用配置的网站源的相对链接和绝对URL被归类为内部链接。指向其他源的链接接收由主题配置的外部链接属性。

• 访问 关于使用相对网站URL的页面.
• 将其与 外部参考 进行比较.

对内部内容使用相对路径。外部来源，如 https://example.com/ 按主题分别分类。

编写便携式MDX#

文章页面、RSS 和 Atom 共享相同的内容管道。互动 脚本从订阅源中移除，但由组件生成的语义HTML， 呼号、维基链接、数学、代码组和图片依然可读。

为了保证输出可靠：

1. 主要解释保持在Markdown。
2. 赋予图片有意义的替代文本和组件语义HTML。
3. 避免在顶层表达中使用浏览器全局。
4. 确保在客户端 JavaScript 运行前，有用信息已可见。
5. 运行 pnpm test 、 pnpm check 和 pnpm build 发布前。

MDX作为Markdown的扩展效果最佳——不是它的替代品。从以下开始 内容纯粹，然后只在它们使得 文章更清晰或更易重复使用。