@astrojs/mdx

此 Astro 集成 能够使用 MDX 组件，并允许你通过 .mdx 文件创建页面。

为什么是 MDX？

MDX 允许你在 Astro 项目的 Markdown 内容中使用变量、JSX 表达式和组件。如果你有现有的用 MDX 编写的内容，这个集成允许你把这些文件带到你的 Astro 项目中。

安装

快速安装

astro add 命令行工具为你自动进行安装。在一个新的终端窗口中运行下列其中一个命令。（如果你不确定你使用的是哪个包管理器，请运行第一个命令）。然后按照提示，在终端中输入“y”（意思是“是”），每一条都是如此。

# Using NPM
npx astro add mdx
# Using Yarn
yarn astro add mdx
# Using PNPM
pnpm astro add mdx

如果你遇到任何问题，请随时在 GitHub 上向我们报告并尝试下面的手动安装步骤。

手动安装

首先，用你的包管理器安装 @astrojs/mdx 包。如果你使用的是 npm 或者不确定哪个包管理器，在终端运行这个：

npm install @astrojs/mdx

然后，使用 integrations 属性将这个集成应用到你的 astro.config.* 文件：

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [mdx()],
  //             ^^^^^
});

编辑器集成

对于 VS Code 的编辑器支持，请安装官方的 MDX 扩展。

对于其他编辑器，请使用 MDX 语言服务器。

使用

通过 Astro MDX 集成，你可以在你的 src/pages/ 目录下添加 .mdx 文件来添加 MDX 页面到你的项目。你也可以导入 .mdx 文件到 .astro 文件。

Astro 的 MDX 集成为标准的 MDX 增加了额外的功能，包括 Markdown 风格的 frontmatter。这允许你使用大部分 Astro 的内置 Markdown 功能，比如一个特殊的 frontmatterlayout 属性。

在我们的 Markdown & MDX 指南中可以看到 MDX 在 Astro 中的工作原理和例子。

访问 MDX 文档，了解使用标准 MDX 功能的情况。

配置

一旦 MDX 集成被安装，在你的 Astro 项目中使用 .mdx 文件就不需要配置。

你可以通过以下选项配置你的 MDX 的渲染方式：

继承自 Markdown 配置的选项
extendMarkdownConfig
recmaPlugins
优化

继承自 Markdown 配置的选项

所有 markdown 配置选项都可以在 MDX 集成中单独配置。这包括 remark 和 rehype 插件、语法高亮等。选项将默认为你的 Markdown 配置中的选项（请参阅 extendMarkdownConfig 选项来修改此选项）。

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkToc from 'remark-toc';
import rehypeMinifyHtml from 'rehype-minify-html';

export default defineConfig({
  integrations: [
    mdx({
      syntaxHighlight: 'shiki',
      shikiConfig: { theme: 'dracula' },
      remarkPlugins: [remarkToc],
      rehypePlugins: [rehypeMinifyHtml],
      remarkRehype: { footnoteLabel: 'Footnotes' },
      gfm: false,
    }),
  ],
});

📚 参见 Markdown 选项参考以获得完整的选项列表。

`extendMarkdownConfig`

类型： boolean
默认值： true

MDX 将默认扩展你的项目现有的 Markdown 配置。要覆盖个别选项，你可以在你的 MDX 配置中进行等价配置。

例如，假设你需要禁用 GitHub-Flavored Markdown，并为 MDX 文件应用一套不同的注释插件。你可以像这样应用这些选项，extendMarkdownConfig 默认为启用：

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  markdown: {
    syntaxHighlight: 'prism',
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      // 继承自 Markdown 的 `syntaxHighlight`

      // Markdown `remarkPlugins` 被忽略，
      // 只启用 `remarkPlugin2`。
      remarkPlugins: [remarkPlugin2],
      // `gfm` 被重写为 `false`
      gfm: false,
    }),
  ],
});

你可能还需要在 MDX 中禁用 markdown 配置扩展。为此，将 extendMarkdownConfig 设置为 false：

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkPlugin1],
  },
  integrations: [
    mdx({
      // Markdown 配置现在被忽略了
      extendMarkdownConfig: false,
      // `remarkPlugins` 没有启用
    }),
  ],
});

`recmaPlugins`

这些是直接修改输出 estree 的插件。这对于在你的 MDX 文件中修改或注入 JavaScript 变量很有用。

我们建议使用 AST Explorer来处理 estree 的输出，并尝试 estree-util-visit 来搜索整个 JavaScript 节点。

优化

类型： boolean | { customComponentNames?: string[] }

这是一个可选的配置设置，用于优化 MDX 输出，以便通过内部 rehype 插件加快构建和渲染速度。如果你的 MDX 文件较多，并注意到构建速度较慢，这可能会很有用。不过，该选项可能会生成一些未转义的 HTML，因此请确保你网站的交互式部分在启用该选项后仍能正常工作。

默认情况下是禁用的。要启用 MDX 优化，请在 MDX 集成配置中添加以下内容：

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [
    mdx({
      optimize: true,
    }),
  ],
});

customComponentNames

类型： string[]

optimize 的一个可选属性，用于防止 MDX 优化器处理通过组件属性传递给导入的 MDX 内容的任何自定义组件。

你需要将这些组件从优化中排除，因为优化器会急切地将内容转换为静态字符串，这将破坏需要动态呈现的自定义组件。

例如，以下内容的预期 MDX 输出应为 <Heading>...</Heading>，而不是每个 "<h1>...</h1>"：

---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---

<Content components={{ ...components, h1: Heading }} />

要使用 customComponentNames 属性配置此优化，指定应视为自定义组件的 HTML 元素名称数组：

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [
    mdx({
      optimize: {
        // 防止优化器处理 `h1` 元素
        // 这些元素将被视为自定义组件
        customComponentNames: ['h1'],
      },
    }),
  ],
});