Skip to navigation

remark-mdx

支持 MDX 语法(JSX、导出/导入、表达式)的备注插件。

内容

这是什么?

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

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

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

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

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

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

安装

这个包是 仅限 ESM。 在 Node.js(版本 16+)中,使用 npm 安装:

Shell
npm install remark-mdx

在 Deno 中使用 esm.sh

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

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

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

使用

TypeScript
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))

产量:

MDX
import a from "b"

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

API

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

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

添加对 MDX 的支持(JSX:<Video id={123} />,导出/导入:export {x} from 'y';表达式:{1 + 1})。

参数
  • optionsOptions,可选) — configuration

返回

什么都没有(undefined)。

Options

配置(TypeScript 类型)。

字段
  • acornOptionsAcornOptions,默认:{ecmaVersion: 2024, locations: true, sourceType: 'module'}) — 橡子的配置; 除 locations 外的所有字段均可设置
  • printWidthnumber,默认:Infinity) — 尝试按此宽度换行语法; 当设置为有限数量(例如,80)时,当标签无法容纳在一行上时,格式化程序将在单独的行上打印属性; 正常行为是打印属性之间有空格而不是行结尾
  • quote'"'"'",默认:'"') — 在属性值周围使用的首选引号
  • quoteSmartboolean,默认:false) — 如果会导致字节数减少,请使用另一个引号
  • tightSelfClosingboolean,默认:false) — 关闭自关闭元素时不要使用额外的空格: <img/> 代替 <img />

创作

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

HTML

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

语法

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

语法树

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

错误

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

类型

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

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

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

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

function myRemarkPlugin() {
  /**
   * @param {import('mdast').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.
    })
  }
}

兼容性

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

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

安全

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

贡献

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

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

许可证

MIT © Titus Wormer

MDX 中文网 - 粤ICP备13048890号