@astrojs/ mdx

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

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

为什么选择 MDX？

¥Why 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.

安装

¥Installation

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

¥Astro includes an astro add command to automate the setup of official integrations. If you prefer, you can install integrations manually instead.

在新的终端窗口中运行以下命令之一。

¥Run one of the following commands in a new terminal window.

npx astro add mdx

pnpm astro add mdx

yarn 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.

手动安装

¥Manual Install

首先，安装 @astrojs/mdx 包：

¥First, install the @astrojs/mdx package:

npm install @astrojs/mdx

pnpm add @astrojs/mdx

yarn add @astrojs/mdx

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

¥Then, apply the 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()],
});

编辑器集成

¥Editor Integration

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

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

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

¥For other editors, use the MDX language server.

用法

¥Usage

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

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

Astro 中的 MDX

¥MDX in Astro

添加 MDX 集成可增强你使用 JSX 变量、表达式和组件进行 Markdown 创作的能力。

¥Adding the MDX integration enhances your Markdown authoring with JSX variables, expressions and components.

它还为标准 MDX 添加了额外的功能，包括支持 MDX 中的 Markdown 样式前言。这允许你使用大部分 Astro 的内置 Markdown 功能。

¥It also adds extra features to standard MDX, including support for Markdown-style frontmatter in MDX. This allows you to use most of Astro’s built-in Markdown features.

.mdx 文件必须使用 MDX 语法编写，而不是使用 Astro 的类似 HTML 的语法。

¥.mdx files must be written in MDX syntax rather than Astro’s HTML-like syntax.

将 MDX 与内容集合结合使用

¥Using MDX with content collections

要将 MDX 文件包含在内容集合中，请确保你的集合加载器配置为从 .mdx 文件加载内容：

¥To include MDX files in a content collection, make sure that your collection loader is configured to load content from .mdx files:

import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
  })
});

export const collections = { blog };

在 MDX 中使用导出的变量

¥Using Exported Variables in MDX

MDX 支持使用 export 语句将变量添加到你的 MDX 内容或将数据导出到导入它的组件。

¥MDX supports using export statements to add variables to your MDX content or to export data to a component that imports it.

例如，你可以从 MDX 页面或组件导出 title 字段以用作 {JSX expressions} 的标题：

¥For example, you can export a title field from an MDX page or component to use as a heading with {JSX expressions}:

export const title = 'My first MDX post'

# {title}

或者，你可以使用 import 和 import.meta.glob() 语句在页面中使用导出的 title：

¥Or you can use that exported title in your page using import and import.meta.glob() statements:

---
const matches = import.meta.glob('./posts/*.mdx', { eager: true });
const posts = Object.values(matches);
---

{posts.map(post => <p>{post.title}</p>)}

导出的属性

¥Exported Properties

使用 import 语句或 import.meta.glob() 时，.astro 组件可以使用以下属性：

¥The following properties are available to a .astro component when using an import statement or import.meta.glob():

file - 绝对文件路径（例如 /home/user/projects/.../file.mdx）。
url - 页面的 URL（例如 /en/guides/markdown-content）。
frontmatter - 包含文件 YAML 前言中指定的任何数据。
getHeadings() - 一个异步函数，返回文件中所有标题（<h1> 到 <h6>）的数组，类型为：{ depth: number; slug: string; text: string }[]。每个标题的 slug 对应于给定标题生成的 ID，可用于锚链接。
<Content /> - 返回文件完整渲染内容的组件。
（任何 export 值） - MDX 文件还可以使用 export 语句导出数据。

在 MDX 中使用 Frontmatter 变量

¥Using Frontmatter Variables in MDX

Astro MDX 集成默认支持在 MDX 中使用 frontmatter。像在 Markdown 文件中一样添加 frontmatter 属性，这些变量可以在模板中使用，也可以在将文件导入到其他地方时作为命名属性使用。

¥The Astro MDX integration includes support for using frontmatter in MDX by default. Add frontmatter properties just as you would in Markdown files, and these variables are available to use in the template, and as named properties when importing the file somewhere else.

---
title: 'My first MDX post'
author: 'Houston'
---

# {frontmatter.title}

Written by: {frontmatter.author}

在 MDX 中使用组件

¥Using Components in MDX

安装 MDX 集成后，你可以在 MDX (.mdx) 文件中导入和使用 Astro 组件和 UI 框架组件，就像在任何其他 Astro 组件中使用它们一样。

¥After installing the MDX integration, you can import and use both Astro components and UI framework components in MDX (.mdx) files just as you would use them in any other Astro component.

如有必要，不要忘记在你的 UI 框架组件上包含 client:directive！

¥Don’t forget to include a client:directive on your UI framework components, if necessary!

请参阅 MDX 文档中使用导入和导出语句的更多示例。

¥See more examples of using import and export statements in the MDX docs.

---
title: My first post
---
import ReactCounter from '../components/ReactCounter.jsx';

I just started my new Astro blog!

Here is my counter component, working in MDX:
<ReactCounter client:load />

使用导入的 MDX 定制组件

¥Custom components with imported MDX

渲染导入的 MDX 内容时，可以通过 components 属性传递定制组件。

¥When rendering imported MDX content, custom components can be passed via the components prop.

---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---
<!-- Creates a custom <h1> for the # syntax, _and_ applies any custom components defined in `content.mdx` -->
<Content components={{...components, h1: Heading }} />

将自定义组件分配给 HTML 元素

¥Assigning Custom Components to HTML elements

使用 MDX，你可以将 Markdown 语法映射到自定义组件而不是标准 HTML 元素。这允许你使用标准 Markdown 语法进行编写，但将特殊的组件样式应用于所选元素。

¥With MDX, you can map Markdown syntax to custom components instead of their standard HTML elements. This allows you to write in standard Markdown syntax, but apply special component styling to selected elements.

将自定义组件导入到 .mdx 文件中，然后导出将标准 HTML 元素映射到自定义组件的 components 对象：

¥Import your custom component into your .mdx file, then export a components object that maps the standard HTML element to your custom component:

import Blockquote from '../components/Blockquote.astro';
export const components = {blockquote: Blockquote}

> This quote will be a custom Blockquote

---
const props = Astro.props;
---
<blockquote {...props} class="bg-blue-50 p-4">
  <span class="text-4xl text-blue-600 mb-2">“</span>
  <slot /> <!-- Be sure to add a `<slot/>` for child content! -->
</blockquote>

请访问 MDX 网站以获取可作为自定义组件覆盖的 HTML 元素的完整列表。

¥Visit the MDX website for a full list of HTML elements that can be overwritten as custom components.

配置

¥Configuration

安装 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 配置继承的选项

¥Options inherited from Markdown config

所有 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 rehypePresetMinify from 'rehype-preset-minify';

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

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 | { ignoreElementNames?: 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,
    }),
  ],
});

`ignoreElementNames`

类型：string[]

Added in: @astrojs/mdx@3.0.0

以前称为 customComponentNames。

¥Previously known as customComponentNames.

optimize 的可选属性，用于防止 MDX 优化器处理某些元素名称，如 custom components passed to imported MDX content via the components prop。

¥An optional property of optimize to prevent the MDX optimizer from handling certain element names, like 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 }} />

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

¥To configure optimization for this using the ignoreElementNames 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
        ignoreElementNames: ['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.

示例

¥Examples

Astro MDX 入门模板展示了如何在 Astro 项目中使用 MDX 文件。