# @diglot/mdast 中文文档

规范地址：https://npmcn.com/package/%40diglot/mdast/

版本：0\.2\.2
npm 元数据更新时间：2026-11-08T11:46:20.219Z
中文译文更新时间：2026-11-12T09:30:03.996Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40diglot/mdast
原文对照：https://npmcn.com/package/%40diglot/mdast/?lang=original
项目主页：https://github.com/danielroe/diglot#readme
源码仓库：https://github.com/danielroe/diglot

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：37 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：10 个
- peer 依赖：satteri ^0\.11\.6
- 首次发布：2026-11-02T18:45:41.655Z
- 最新版本发布：2026-11-08T11:46:19.922Z
- 近 30 天下载量：3395（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

diglot 注释/ mdast 适配器

## 安装

```sh
npm install @diglot/mdast
```

也可以使用：`pnpm add @diglot/mdast`、`yarn add @diglot/mdast`、`bun add @diglot/mdast`

## README

# @ diglot/ mdast (英语)

注释/ mdast 适配器 [挖掘机](https://npmcn.com/package/README.md),用于标出 `remark-parse`, (中文(简体) ), `remark-gfm`, (中文(简体) ), `remark-frontmatter` 财务报告和审定财务报表 `remark-mdc`,用于 [磁共振](https://npmcn.com/package/%40diglot/mdast/#readme-mdx)适合 Astro 、 Docuraurus 、 星光 或 平地标记下源 .

```bash
pnpm add @diglot/mdast @diglot/core
```

## 使用量

```ts
import { apply, extract } from '@diglot/mdast'

const segments = await extract(markdown, { file: 'docs/intro.md' })

const { markdown: translated, report } = await apply(markdown, new Map([[segments[0].hash, 'Introduction']]))
```

-   `extract(source, { file, format, parser, policy })` 返回与 `@diglot/comark` 用于同一文档,并有节点精确的行位置。 从源头切出受保护的跨度.
    
-   `apply(source, translations, { format, parser, policy })` 验证每个翻译并将其切入源,所以所有外翻译单元都被保存为字节. Frontmatter和YAML道具被重写为YAML scalar;内置道具保留其属性语法;代码注释保留其缩进和注释语法. 无法在来源中找到的单位报告为 `unaddressable` 并保留其源文本.
    
-   `apply(source, translations, { onSegment })` 电话 `onSegment` 带有 [`ApplySegmentEvent`](https://npmcn.com/package/%40diglot/core#apply-events) 每个段。 属性设置为 `target.setAttribute(name, value)` 标题、段落和表格单元格返回为 `annotations`;其他部分有 `null` 目标. `annotate(tree, annotations)` 设定为 `data.hProperties` 将紧凑的列表项目的段落作为 `<span>` 因此他们的属性到达了 HTML.
    
    ```ts
    const { markdown: translated, annotations } = await apply(markdown, segment => records.get(segment.hash), {
      onSegment(event) {
        if (event.outcome === 'missing' || event.outcome === 'rejected')
          event.target?.setAttribute('lang', 'en')
      },
    })
    const tree = processor.parse(translated)
    annotate(tree, annotations)
    ```
    
-   `parse(source, { format, parser })` 暴露适配器使用的管道.
    

## 解析器

`extract`, (中文(简体) ), `apply` 财务报告和审定财务报表 `parse` 带一个 `parser` 选项. `remark` 默认值. `satteri` 用途 [萨特里](https://satteri.bruits.org/),用Rust写的Markdown 解析器,速度要快得多:

```bash
pnpm add satteri
```

```ts
const segments = await extract(markdown, { parser: 'satteri' })
```

Sätteri读取指令的方式与Starlight使用的评论指令相同. `:::` 边框等块被翻译为组件,其中任意一个是 parser,而Sätteri 则有其标题(`:::tip[Title]`)也译出. 带有标签或属性的内含指令,例如 `:badge[New]`,作为占位符保存。 Sätteri 没有 MDC 支持, 因此块组件如 `::card` 没有解析,它们的标记可以最终被翻译成文本。 保留 `remark` 用于 MDC 源代码。 对于其他的平分法,两个解析器都产生相同的片段和散列,因此现有的译名继续应用. 一个例外: Sätteri 跳过 TOML 前题(`+++`评注为一款。 传出同样的 `parser` 改为 `extract` 财务报告和审定财务报表 `apply`。 。 。 .

## 磁共振

MDX是加减JSX组件, `{expressions}` 财务报告和审定财务报表 `import` 财务报告和审定财务报表 `export` 发言。 适配器在 `file` 结束于 `.mdx`,或者当你通过 `format: 'mdx'`数字 :

```ts
const segments = await extract(source, { file: 'docs/cards.mdx' })
```

两个解析器都读取了 MDX, 注释为 `remark-mdx` 和Sätteri 和它自己的 MDX parser, 它们产生相同的片段和散列。 MDX从不读作MDC,但是 `:::` 指令,如"星光"边框,用两种格式阅读。 一个例外: Docusaurus 提醒在空格后加一个标题(`:::tip Title`) (中文(简体) ). Sätteri将其读作指令并删除标题,而评论只读出括号中的标题并保留这些行为正文.

JSX元素内部的文本像MDC组件的内容一样被翻译. 一个组件的策略列表也被翻译的字符串道具,与元素的kebab-case名称相匹配,所以 `<LinkCard title="…">` 使用 `link-card`。带有表达值的道具,例如 `title={name}`独自一人 句子中的JSX元素,例如: `<kbd>Ctrl</kbd>`,以及诸如 `{count}` 成为占位符. `import` 财务报告和审定财务报表 `export` 他们自己的语言和表达方式,包括评论,不是翻译.

校验拒绝包含未脱逃翻译 `{` 或 HTML, 以及 `apply` 逃过其他的劫难 `<` mDX会读作标签,所以应用翻译不能在页面上添加JSX或表达. 一个被翻译道克保留了源的引文字符,除非该值包含该字符而不是另一个字符. 当值包含两者时,引用字符为 `&quot;` 或者说 `&#39;`。 。 。 .

标题锚由出自标题文本的渲染器生成,所以被翻译的标题会得到翻译锚地,除非出自渲染器支持明显的id.

## 常见问题

### @diglot/mdast 是什么？

diglot 注释/ mdast 适配器

### 如何安装 @diglot/mdast？

在项目目录运行 npm install @diglot/mdast，或使用 pnpm add / yarn add / bun add。

### @diglot/mdast 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @diglot/mdast 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @diglot/mdast 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @diglot/mdast 可以商用吗？

@diglot/mdast 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @diglot/mdast 的下载量有多少？

根据 npm 官方下载统计，@diglot/mdast 在 2026/10/12 – 2026/11/10 这 30 天内被下载 3,395 次，日均约 113 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @diglot/mdast 还在维护吗？

最新版本 0\.2\.2 发布于 2026/11/08（3 天前）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/11/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。