@astrojs/mdx

此 Astro 集成 能够使用 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默认支持 Markdown。然而，为了支持 MDX 编辑器，你可能希望在你的 VSCode 配置中添加以下设置，这可以确保编写 MDX 文件时提供类似 Markdown 的编辑体验。

{
  "files.associations": {
    "*.mdx": "markdown"
  }
}

通过 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
• 优化

除了 drafts，所有的markdown 配置选项可以在 MDX 集成中单独配置。这包括备注和 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 选项参考 以获得完整的选项列表。

• 类型： 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` 没有启用
    }),
  ],
});

这些是直接修改输出 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,
    }),
  ],
});

• 类型： 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'],
      },
    }),
  ],
});

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

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

如需帮助，请查看 Discord 上的 #support 频道。我们友好的支持小组成员将在这里提供帮助！

你也可以查看我们的 Astro 集成文档，了解更多关于集成的信息。

这个项目由 Astro 的核心团队维护，欢迎你提交 issue 或 PR！

有关该集成的变化历史，请参阅 CHANGELOG.md。

更多集成