跳转到内容

@astrojs/mdx

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

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

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

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

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

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

Terminal window
npm install @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 配置的选项

段落标题 继承自 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,
}),
],
});

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

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

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

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

  • 类型: boolean | { customComponentNames?: 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,
}),
],
});
  • 类型: 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 元素名称数组:

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

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

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

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

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

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

其他

UI 框架

SSR 适配器

其他