Question

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

为什么是 MDX？

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

安装

Astro 包含了一个 astro add 命令，用于自动设置官方集成。如果你愿意，可以改为手动安装集成。

在新的终端窗口中运行下面其中一个命令。

• npm
• pnpm
• Yarn

npx astro add mdx

pnpm astro add mdx

yarn astro add mdx

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

手动安装

首先，安装 @astrojs/mdx 包：

• npm
• pnpm
• Yarn

npm install @astrojs/mdx

pnpm add @astrojs/mdx

yarn add @astrojs/mdx

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

astro.config.mjs

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
• optimize

继承自 Markdown 配置的选项

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

astro.config.mjs

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

警告

MDX 不支持以字符串形式传递备注和 rehype 插件。你应该安装、导入并应用插件功能来代替。

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

extendMarkdownConfig

• 类型： boolean
• 默认值： true

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

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

astro.config.mjs

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：

astro.config.mjs

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 节点。

optimize

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

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

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

astro.config.mjs

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


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

ignoreElementNames

• 类型： string[]

添加于： @astrojs/mdx@3.0.0 新

以前称为 customComponentNames。

optimize 的一个可选属性，用于防止 MDX 优化器处理某些元素名称，例如通过 components 属性传递给导入的 MDX 内容的自定义组件。

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

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

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


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

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

astro.config.mjs

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


export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: {
        // 防止优化器处理 `h1` 元素
        ignoreElementNames: ['h1'],
      },
    }),
  ],
});

请注意，如果你的 MDX 文件使用 export const components = {...} 配置自定义组件，则你无需手动配置此选项。优化器将自动检测它们。

例子

• Astro MDX 启动模板显示了如何在你的 Astro 项目中使用 MDX 文件。

更多集成

UI 框架

• 

  @astrojs/alpinejs

• 

  @astrojs/lit

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

SSR 适配器

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

其他集成

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap

• 

  @astrojs/tailwind

Recipes