@astrojs/mdx

此 Astro 整合 允许使用 MDX 组件，并允许你将页面创建为 .mdx 文件。

英This Astro integration enables the usage of MDX components and allows you to create pages as .mdx files.

为什么选择 MDX？

MDX 允许你在 Astro 中进行在 Markdown 内容中使用变量、JSX 表达式和组件。如果你有在 MDX 中创作的现有内容，此集成允许你将这些文件带到你的 Astro 项目中。

英MDX allows you to use variables, JSX expressions and components within Markdown content in Astro. If you have existing content authored in MDX, this integration allows you to bring those files to your Astro project.

安装

快速安装

astro add 命令行工具会自动为你进行安装。在新的终端窗口中运行以下命令之一。（如果你不确定正在使用哪个包管理器，请运行第一个命令。）然后，按照提示操作，并在终端中为每个包键入 “y”（即 “yes”）。

英The astro add command-line tool automates the installation for you. Run one of the following commands in a new terminal window. (If you aren’t sure which package manager you’re using, run the first command.) Then, follow the prompts, and type “y” in the terminal (meaning “yes”) for each one.

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

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

英If you run into any issues, feel free to report them to us on GitHub and try the manual installation steps below.

手动安装

首先，使用包管理器安装 @astrojs/mdx 包。如果你正在使用 npm 或不确定，请在终端中运行以下命令：

英First, install the @astrojs/mdx package using your package manager. If you’re using npm or aren’t sure, run this in the terminal:

npm install @astrojs/mdx

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

英Then, apply this integration to your astro.config.* file using the integrations property:

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

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

编辑器集成

要获得 VS Code 中的编辑器支持，请安装官方 MDX 扩展。

英For editor support in VS Code, install the official MDX extension.

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

英For other editors, use the MDX language server.

用法

通过 Astro MDX 集成，你可以通过在 src/pages/ 目录中添加 .mdx 文件来实现将 MDX 页面添加到你的项目中。你还可以将导入 .mdx 文件转换为 .astro 文件。

英With the Astro MDX integration, you can add MDX pages to your project by adding .mdx files within your src/pages/ directory. You can also import .mdx files into .astro files.

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

英Astro’s MDX integration adds extra features to standard MDX, including Markdown-style frontmatter. This allows you to use most of Astro’s built-in Markdown features like a special frontmatter layout property.

通过 Markdown 和 MDX 指南中的示例了解 MDX 在 Astro 中的工作原理。

英See how MDX works in Astro with examples in our Markdown & MDX guide.

访问 MDX 文档了解如何使用标准 MDX 功能。

英Visit the MDX docs to learn about using standard MDX features.

配置

安装 MDX 集成后，无需进行任何配置即可在 Astro 项目中使用 .mdx 文件。

英Once the MDX integration is installed, no configuration is necessary to use .mdx files in your Astro project.

你可以使用以下选项配置 MDX 的渲染方式：

英You can configure how your MDX is rendered with the following options:

从 Markdown 配置继承的选项
extendMarkdownConfig
recmaPlugins
optimize

从 Markdown 配置继承的选项

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

英All markdown configuration options can be configured separately in the MDX integration. This includes remark and rehype plugins, syntax highlighting, and more. Options will default to those in your Markdown config (see the extendMarkdownConfig option to modify this).

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

:::caution 提醒 MDX 不支持将 remark 和 rehype 插件作为字符串传递。你应该安装、导入并应用插件功能。 :::

📚 有关选项的完整列表，请参阅 Markdown 选项参考。

英📚 See the Markdown Options reference for a complete list of options.

`extendMarkdownConfig`

类型： boolean
默认： true

MDX 默认会扩展你项目的现有 Markdown 配置。要覆盖各个选项，你可以在 MDX 配置中指定其等效项。

英MDX will extend your project’s existing Markdown configuration by default. To override individual options, you can specify their equivalent in your MDX configuration.

例如，假设你需要禁用 GitHub 风格的 Markdown 并为 MDX 文件应用一组不同的 remark 插件。你可以像这样应用这些选项，默认情况下启用 extendMarkdownConfig：

英For example, say you need to disable GitHub-Flavored Markdown and apply a different set of remark plugins for MDX files. You can apply these options like so, with extendMarkdownConfig enabled by default:

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

export default defineConfig({
  markdown: {
    syntaxHighlight: 'prism',
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      // `syntaxHighlight` inherited from Markdown

      // Markdown `remarkPlugins` ignored,
      // only `remarkPlugin2` applied.
      remarkPlugins: [remarkPlugin2],
      // `gfm` overridden to `false`
      gfm: false,
    }),
  ],
});

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

英You may also need to disable markdown config extension in MDX. For this, set extendMarkdownConfig to false:

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

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkPlugin1],
  },
  integrations: [
    mdx({
      // Markdown config now ignored
      extendMarkdownConfig: false,
      // No `remarkPlugins` applied
    }),
  ],
});

`recmaPlugins`

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

英These are plugins that modify the output estree directly. This is useful for modifying or injecting JavaScript variables in your MDX files.

我们建议使用 AST 资源管理器使用 estree 输出，并尝试 estree-util-visit 跨 JavaScript 节点进行搜索。

英We suggest using AST Explorer to play with estree outputs, and trying estree-util-visit for searching across JavaScript nodes.

`optimize`

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

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

英This is an optional configuration setting to optimize the MDX output for faster builds and rendering via an internal rehype plugin. This may be useful if you have many MDX files and notice slow builds. However, this option may generate some unescaped HTML, so make sure your site’s interactive parts still work correctly after enabling it.

默认情况下禁用此功能。要启用 MDX 优化，请将以下内容添加到 MDX 集成配置中：

英This is disabled by default. To enable MDX optimization, add the following to your MDX integration configuration:

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

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

`customComponentNames`

类型： string[]

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

英An optional property of optimize to prevent the MDX optimizer from handling any custom components passed to imported MDX content via the components prop.

你需要从优化中排除这些组件，因为优化器预先将内容转换为静态字符串，这将破坏需要动态渲染的自定义组件。

英You will need to exclude these components from optimization as the optimizer eagerly converts content into a static string, which will break custom components that needs to be dynamically rendered.

例如，以下的预期 MDX 输出是 <Heading>...</Heading> 代替每个 "<h1>...</h1>"：

英For example, the intended MDX output of the following is <Heading>...</Heading> in place of every "<h1>...</h1>":

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

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

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

英To configure optimization for this using the customComponentNames property, specify an array of HTML element names that should be treated as custom components:

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

export default defineConfig({
  integrations: [
    mdx({
      optimize: {
        // Prevent the optimizer from handling `h1` elements
        // These will be treated as custom components
        customComponentNames: ['h1'],
      },
    }),
  ],
});

注意，如果你的 MDX 文件是使用 export const components = { ... } 配置自定义组件，那么你不需要手动配置这个选项。优化器会自动检测它们。

英Note that if your MDX file configures custom components using export const components = { ... }, then you do not need to manually configure this option. The optimizer will automatically detect them.