---
title: "Markdown 与 MDX"
description: "使用 Markdown 或 MDX 编写内容，无需导入即可使用组件，并在构建时捕获错误标签。"
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus-docs.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Markdown 与 MDX

内容格式为 Markdown（`.md`）或 MDX（`.mdx`）。MDX 允许你将组件直接嵌入正文——卡片、标签页、步骤、提示框，以及你构建的任何组件。

<h2 id="links-under-a-deployment-base">部署基础路径下的链接</h2>

将站内链接写为逻辑根路径，不要包含 Astro 的部署基础路径。如果站点部署时配置了 `base: "/docs"`，应写 `[Installation](/installation)`，而不是 `[Installation](/docs/installation)`。Nimbus 会在构建时自动添加 `/docs`。

这适用于 Markdown 链接、引用定义、原生 `<a href>` 属性和静态组件的 `href` 字符串。相对链接、外部 URL、锚点、查询字符串、代码和动态 JSX 表达式不受影响。

如果需要在组件或路由代码中计算链接，从 `@cloudflare/nimbus-docs/runtime` 导入 `withBase` 并调用一次：

```ts
import { withBase } from "@cloudflare/nimbus-docs/runtime";

const href = withBase("/installation", import.meta.env.BASE_URL);
```

不要将已包含基础路径的路径传给 `withBase`；当基础路径为 `/docs` 时，`withBase("/docs/installation", "/docs")` 会故意生成 `/docs/docs/installation`。

<h2 id="the-components-registry">组件注册表</h2>

在 `src/components.ts` 中列出的组件可在所有 MDX 文件中**无需导入**直接使用：

```ts title="src/components.ts"
import { Aside } from "./components/ui/aside";
import { Card } from "./components/ui/card";
import { CardGrid } from "./components/ui/card-grid";

export const components = {
  Aside,
  Card,
  CardGrid,
};
```

```mdx
<CardGrid>
  <Card title="Fast">Built on Astro.</Card>
</CardGrid>
```

未在注册表中的组件必须在文件顶部导入：

```mdx
import { FileTree } from "@/components/ui/file-tree";

<FileTree>
- src/
</FileTree>
```

<h2 id="build-time-validation">构建时校验</h2>

在构建前会执行一次内容检查，将 `src/content/**/*.mdx` 中每个 PascalCase 标签名与注册表及文件内导入进行比对。未知组件、小写用法和缺失的导入会**导致构建失败**，而不是在部署页面上静默渲染为纯文本。你可以在集成选项中设置 `validateMdx: false` 来关闭此功能。

<h2 id="admonitions">提示框</h2>

在 `.mdx` 文件中，Sätteri 会解析 `:::` 指令，Nimbus 使用 `<Aside>` 渲染它们：

```mdx
:::tip
This becomes an Aside.
:::
```

<h3 id="rendered-examples">渲染示例</h3>

这些提示框使用指令语法编写，通过 Sätteri 渲染。

:::note
A default note with **bold text**, a [link](#admonitions), and `inline code`.
:::

:::tip[Worth knowing]
Use a title to describe the guidance in your callout.
:::

:::warning[Say "hello"]
Quoted titles stay plain strings. The `warning` alias uses the caution variant.
:::

:::danger[`Cache-Control` header]
Formatting in the title stays literal; body formatting such as **this** still works.
:::

::::note[Nested guidance]
The outer note contains a tip and a source example.

:::tip
Nested callouts use the same Aside component.
:::

```mdx
:::note
This fenced example stays code.
:::
```
::::

<h3 id="syntax-and-behavior">语法与行为</h3>

内置类型：`note`、`info`、`tip`、`caution`、`warning`、`important`、`danger`。可通过 `admonitions: { typeAliases: { heads: "tip" } }` 添加同义词。`Aside` 必须在你的组件注册表中（默认模板已导出）。

标题使用现有的纯 `title` 属性。Sätteri 输出字符串属性；引号和表达式样式的文本不会被求值。标题中的标记保持为纯文本。指令标题仍需是有效的 MDX 语法，因为 Sätteri 在 AST 遍历之前解析文档。对于任意文本（如未闭合的 `<T>` 或 `{`），请使用组件的字符串属性：

```mdx
<Aside title="Use <T>">Body content.</Aside>
```

无需更新 Aside 组件。

Sätteri 解析指令及其正文；Nimbus 将识别的指令节点映射为 Aside。正文缩进不会被重写。代码示例、frontmatter、表达式和 JSX 属性仍受保护。现有的首行正文形式为兼容性而保留。

嵌套和围栏终止遵循 Sätteri 的原生语法。嵌套提示框使用更长的外层围栏：

```mdx
::::note
Outer content.

:::tip
Inner content.
:::
::::
```

未知指令默认保持为纯文本。如果你的 Sätteri 处理器显式启用了原生指令，未识别的节点仍可供你的 AST 插件使用。包含独立回车符的文件也保持为纯文本，因为安装的原生指令解析器不能一致地处理这些行尾格式；LF 和 CRLF 是支持的。

此功能需要 Nimbus 的原生 Sätteri MDX 流水线。兼容的显式 Sätteri 处理器是支持的。对于 unified 或其他自定义处理器，请设置 `admonitions: false` 并保留该处理器的提示框实现。`.md` 文件、原始导入和 `admonitions.contentDirs` 之外的文件不受影响。使用 `admonitions.skip` 进行逐文件排除。

<h2 id="extending-markdown">扩展 Markdown</h2>

使用 `markdown.mdastPlugins` 扩展 Sätteri 的 Markdown AST 转换，使用 `markdown.hastPlugins` 进行 HTML AST 转换。Nimbus 通过 `@cloudflare/nimbus-docs/markdown` 提供原生插件：

```ts title="astro.config.ts"
import { externalLinks } from "@cloudflare/nimbus-docs/markdown";

nimbus(config, {
  markdown: { hastPlugins: [externalLinks()] },
});
```

Source: https://nimbus-docs.cn/writing/markdown-and-mdx/index.mdx