Markdown 与 MDX | Nimbus 中文文档

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

部署基础路径下的链接

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

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

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

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。

组件注册表

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

src/components.tsts

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,
};

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

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

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

<FileTree>
- src/
</FileTree>

构建时校验

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

提示框

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

:::tip
This becomes an Aside.
:::

渲染示例

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

语法与行为

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

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

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

无需更新 Aside 组件。

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

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

::::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 进行逐文件排除。

扩展 Markdown

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

astro.config.tsts

import { externalLinks } from "@cloudflare/nimbus-docs/markdown";

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