remark-mdx

支持 MDX 语法（JSX、导出/导入、表达式）的 remark 插件。

¥remark plugin to support the MDX syntax (JSX, export/import, expressions).

内容

¥Contents

• 这是什么？

  ¥What is this?

• 我什么时候应该使用这个？

  ¥When should I use this?

• 安装

  ¥Install

• 使用

  ¥Use

• API

  • unified().use(remarkMdx[, options])

  • Options

• 创作

  ¥Authoring

• HTML

• 语法

  ¥Syntax

• 语法树

  ¥Syntax tree

• 错误

  ¥Errors

• 类型

  ¥Types

• 兼容性

  ¥Compatibility

• 安全

  ¥Security

• 贡献

  ¥Contribute

• 许可证

  ¥License

这是什么？

¥What is this?

该软件包是一个 unified (remark) 插件，用于启用 MDX 添加的 Markdown 扩展：JSX (<x/>)、导出/导入 (export x from 'y') 和表达式 {{1 + 1}}。你可以使用此插件添加对解析和序列化它们的支持。

¥This package is a unified (remark) plugin to enable the extensions to markdown that MDX adds: JSX (<x/>), export/import (export x from 'y'), and expression {{1 + 1}}. You can use this plugin to add support for parsing and serializing them.

此插件不处理 MDX 如何编译为 JavaScript 或评估并渲染为 HTML。这是 @mdx-js/mdx 做的。

¥This plugin does not handle how MDX is compiled to JavaScript or evaluated and rendered to HTML. That’s done by @mdx-js/mdx.

我什么时候应该使用这个？

¥When should I use this?

如果你正在处理 MDX 语法并与 remark、rehype 和 unity 的其余部分集成，则此插件非常有用。一些示例用例是当你想要检查语法或将其编译为 JavaScript 之外的其他内容时。

¥This plugin is useful if you’re dealing with the MDX syntax and integrating with remark, rehype, and the rest of unified. Some example use cases are when you want to lint the syntax or compile it to something other that JavaScript.

如果你不使用插件并想要访问语法树，则可以使用 mdast-util-from-markdown 和 mdast-util-mdx。

¥If you don’t use plugins and want to access the syntax tree, you can use mdast-util-from-markdown with mdast-util-mdx.

但通常情况下，你需要向上移动一层：@mdx-js/mdx。该包是将 MDX 转换为 JavaScript 的核心编译器，为你提供了最大的控制权。甚至更高：如果你使用打包器（Rollup、esbuild、webpack）或打包器附带的站点构建器（Next.js）或构建系统（Vite），那么最好使用集成：见 § 集成。

¥Typically though, you’d want to move a layer up: @mdx-js/mdx. That package is the core compiler for turning MDX into JavaScript which gives you the most control. Or even higher: if you’re using a bundler (Rollup, esbuild, webpack), or a site builder (Next.js) or build system (Vite) which comes with a bundler, you’re better off using an integration: see § Integrations.

安装

¥Install

这个包是 仅限 ESM。在 Node.js（版本 16+）中，使用 npm 安装：

¥This package is ESM only. In Node.js (version 16+), install with npm:

npm install remark-mdx

在 Deno 中使用 esm.sh：

¥In Deno with esm.sh:

import remarkMdx from 'https://esm.sh/remark-mdx@3'

在带有 esm.sh 的浏览器中：

¥In browsers with esm.sh:

<script type="module">
  import remarkMdx from 'https://esm.sh/remark-mdx@3?bundle'
</script>

使用

¥Use

import {remark} from 'remark'
import remarkMdx from 'remark-mdx'

const file = await remark()
  .use(remarkMdx)
  .process('import a from "b"\n\na <b /> c {1 + 1} d')

console.log(String(file))

产量：

¥Yields:

import a from "b"

a <b/> c {1 + 1} d

API

该包不导出任何标识符。默认导出为 remarkMdx。

¥This package exports no identifiers. The default export is remarkMdx.

unified().use(remarkMdx[, options])

添加对 MDX 的支持（JSX：<Video id={123} />，导出/导入：export {x} from 'y'；表达式：{1 + 1}）。

¥Add support for MDX (JSX: <Video id={123} />, export/imports: export {x} from 'y'; and expressions: {1 + 1}).

参数

¥Parameters

• options（Options，可选） - 配置

  ¥options (Options, optional) — configuration

返回

¥Returns

什么都没有（undefined）。

¥Nothing (undefined).

Options

配置（TypeScript 类型）。

¥Configuration (TypeScript type).

字段

¥Fields

• acornOptions (AcornOptions, 默认值: {ecmaVersion: 2024, locations: true, sourceType: 'module'}) — acorn 的配置；除 locations 外的所有字段均可设置

  ¥acornOptions (AcornOptions, default: {ecmaVersion: 2024, locations: true, sourceType: 'module'}) — configuration for acorn; all fields except locations can be set

• printWidth (number, 默认值: Infinity) — 尝试以此宽度换行语法；当设置为有限数量（例如，80）时，当标签无法容纳在一行上时，格式化程序将在单独的行上打印属性；正常行为是打印属性之间有空格而不是行结尾

  ¥printWidth (number, default: Infinity) — try and wrap syntax at this width; when set to a finite number (say, 80), the formatter will print attributes on separate lines when a tag doesn’t fit on one line; the normal behavior is to print attributes with spaces between them instead of line endings

• quote（'"' 或 "'"，默认值：'"'）- 在属性值周围使用的首选引号

  ¥quote ('"' or "'", default: '"') — preferred quote to use around attribute values

• quoteSmart (boolean，默认值：false) — 如果导致字节数减少，则使用另一个引号

  ¥quoteSmart (boolean, default: false) — use the other quote if that results in less bytes

• tightSelfClosing (boolean，默认值：false) — 关闭自关闭元素时不要使用额外的空格：<img/> 代替 <img />

  ¥tightSelfClosing (boolean, default: false) — do not use an extra space when closing self-closing elements: <img/> instead of <img />

创作

¥Authoring

有关如何编写 MDX 的建议，请参阅每个相应的自述文件：

¥For recommendations on how to author MDX, see each corresponding readme:

• ESM

• JSX

• expressions

• MDX 中没有的 CommonMark 功能

  ¥CommonMark features not in MDX

HTML

MDX 在 HTML 中没有表示形式。不过，当你处理 MDX 时，你可能会感到匆忙。你可以通过配置 remark-rehype 和 passThrough: ['mdxjsEsm', 'mdxFlowExpression', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxTextExpression'] 来启用将 MDX 传递到 hast。

¥MDX has no representation in HTML. Though, when you are dealing with MDX, you will likely go through hast. You can enable passing MDX through to hast by configuring remark-rehype with passThrough: ['mdxjsEsm', 'mdxFlowExpression', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxTextExpression'].

语法

¥Syntax

有关这些功能的语法的信息，请参阅每个相应的自述文件：

¥For info on the syntax of these features, see each corresponding readme:

• ESM

• JSX

• expressions

• MDX 中没有的 CommonMark 功能：n/a

  ¥CommonMark features not in MDX: n/a

语法树

¥Syntax tree

有关这些功能的语法树的信息，请参阅每个相应的自述文件：

¥For info on the syntax tree of these features, see each corresponding readme:

• ESM

• JSX

• expressions

• MDX 中没有的 CommonMark 功能：n/a

  ¥CommonMark features not in MDX: n/a

错误

¥Errors

有关引发错误的信息，请参阅每个相应的自述文件：

¥For info on what errors are thrown, see each corresponding readme:

• ESM

• JSX

• expressions

• MDX 中没有的 CommonMark 功能：n/a

  ¥CommonMark features not in MDX: n/a

类型

¥Types

该包完全采用 TypeScript 类型。它导出附加类型 Options。

¥This package is fully typed with TypeScript. It exports the additional type Options.

如果你正在使用语法树，则可以通过添加引用向 @types/mdast 注册新节点类型：

¥If you’re working with the syntax tree, you can register the new node types with @types/mdast by adding a reference:

// Register MDX nodes in mdast:
/// <reference types="remark-mdx" />

/**

 * @import {Root} from 'mdast'
 */

import {visit} from 'unist-util-visit'

function myRemarkPlugin() {
  /**

   * @param {Root} tree

   *   Tree.

   * @returns {undefined}

   *   Nothing.
   */
  return function (tree) {
    visit(tree, function (node) {
      console.log(node) // `node` can now be one of the MDX nodes.
    })
  }
}

兼容性

¥Compatibility

由统一集体维护的项目与 Node.js 的维护版本兼容。

¥Projects maintained by the unified collective are compatible with maintained versions of Node.js.

当我们削减新的主要版本时，我们会放弃对未维护的 Node.js 版本的支持。这意味着我们尝试保持当前版本 remark-mdx@^3 与 Node.js 16 兼容。

¥When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, remark-mdx@^3, compatible with Node.js 16.

安全

¥Security

请参阅我们网站上的 § 安全 了解信息。

¥See § Security on our website for information.

贡献

¥Contribute

请参阅我们网站上的 § 贡献 了解入门方法。请参阅 § 支持 了解获取帮助的方法。

¥See § Contribute on our website for ways to get started. See § Support for ways to get help.

该项目有 行为守则。通过与此存储库、组织或社区交互，你同意遵守其条款。

¥This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

许可证

¥License

MIT © Titus Wormer