# @djot/djot 中文文档

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

版本：0\.3\.2
npm 元数据更新时间：2024-12-19T03:57:12.064Z
中文译文更新时间：2026-11-12T12:21:08.210Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40djot/djot
原文对照：https://npmcn.com/package/%40djot/djot/?lang=original

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

- 包体积（解压后）：349 kB，35 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=17\.0\.0
- 运行依赖：0 个
- 首次发布：2023-01-11T18:16:57.582Z
- 最新版本发布：2024-12-19T03:57:11.864Z
- 近 30 天下载量：19459（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 0 个）

## 中文简介

Djot 光标语言转换库

## 安装

```sh
npm install @djot/djot
```

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

## README

# djot.js (英语)

用于解析和 绘制光标格式 [欢呼声](https://djot.net/)。 。 。 .

这是重写 [djot的原始卢瓦 执行](https://github.com/jgm/djot.lua)。 。 。 . 它正在驱动 [欢呼声 游乐场](https://djot.net/playground)。 。 。 .

## 脚本 API

这些是运行后可用的 `npm install`,这将 安装库的构建依赖性 :

| `npm run ...` | 说明 |
| --- | --- |
| `build` | 编译和捆绑源到 `lib` 财务报告和审定财务报表 `dist` |
| `test` | 运行测试 |
| `bench` | 运行基准 |

## 安装命令行工具

您可以安装命令行工具 `djot` 通过

```
npm install -g @djot/djot
```

`djot --help` 将概述各种备选办法。 为了更多 大量文档、使用 `man djot` 或见 [在线的男性页面](https://github.com/jgm/djot.js/blob/main/doc/djot.md)。 。 。 .

你用得着 `djot` 改为

-   从 djot 转换为 HTML
-   显示 djot 解析器生成的低等事件流
-   以 JSON 或紧凑形式显示 djot 剖析器生成的 AST
-   从 JSON 格式化 djot AST 转换为 djot 或 HTML
-   使用过滤器修改 AST
-   从 djot 转换为 pandoc JSON , 它可以通过 pandoc 读取
-   将 pandoc JSON( 或 djot) 转换为 djot

例如,转换一个 `gfm` 文档 `mydoc.md` 欢乐,

```
pandoc mydoc.md -f gfm -t json | djot -f pandoc -t djot > mydoc.dj
```

并转换回 `gfm`, (中文(简体) ),

```
djot mydoc.dj -t pandoc | pandoc -f json -t gfm
```

## 光盘N

该图书馆可通过下列途径提供: `unpkg` CDN: (中文(简体) )

```html
<script src="https://unpkg.com/@djot/djot@0.2.5/dist/djot.js"></script>
```

(替换) `0.2.5` 带有您想要使用的版本。 )

## 图书馆 API

### 向 AST 狂欢

`parse(input : string, options : ParseOptions = {})`

使用实例:

```js
djot.parse("hello _there_", {sourcePositions: true});
```

`options` 可拥有下列(可选)字段:

-   `sourcePositions : boolean`: 在AST中包括来源位置
-   `warn : (message : Warning) => void`数字 : 函数用来处理来自 parser 的警告.

可用 `render()` 方法,所以 例如,向控制台发出警告时,您可以:

```
{ warn: (warning) => console.log(warning.render()) }
```

或者,您可以直接访问字段 `message` (弦声), `offset` (如果定义,数字), 财务报告和审定财务报表 `pos` (单位:千美元)`{ line: number, col: number, offset: number }` 如果定义).

### 解析一串事件

`parseEvents(input : string, options : Options = {})`

展出一个活动显示器,每个显示形式 `{startpos : number, endpos : number, annot : string}`。 。 。 . 使用实例:

```js
for (let event of parseEvents("Hi _there_")) {
  console.log(event)
}
```

这个 `Options` 对象有一个 `warn` 描述的属性 `parse`, (中文(简体) ), 见上文.

### 漂亮地印着欢乐AST

`renderAST(doc : Doc) : string`

使用实例:

```js
console.log(djot.renderAST(djot.parse("hi _there_")));
```

### 将 djot AST 渲染到 HTML

`renderHTML(ast : Doc, options : HTMLRenderOptions = {})`

`HTMLRenderOptions` 扩展 `Options` 带有 `overrides` 字段,该字段将节点标记显示为其渲染器的覆盖.

使用实例:

```js
console.log(djot.renderHTML(djot.parse("- _hi_",{sourcePositions:true})));
```

覆盖的简单示例 :

```js
djot.renderHTML(
  djot.parse("_hi_", { sourcePositions: true }),
  { 
    overrides: {
      emph: (node, renderer) => {
        return `<span class="emphasized">${renderer.renderChildren(node)}</span>`;
      }
    } 
  });
```

该产量: `<span class="emphasized">hi</span>`。 。 。 .

### 欢乐

`renderDjot(doc : Doc, options : DjotRenderOptions = {}) : string`

`DjotRenderOptions` 扩展 `Options` 带有 `wrapWidth : number` 字段. 其影响如下:

-   `wrapWidth > 0`: 输出被包裹到宽度中, 并有 “ s软 break” 表现得像一个空间.
-   `wrapWidth = 0`: 输出没有被包; `soft_break` 调制 作为换行符.
-   `wrapWidth = -1`: 输出没有被包; `soft_break` 调制 作为一个空间.

使用实例:

```js
console.log(djot.renderDjot(djot.parse("_Hello_ world"), {wrapWidth: 64}));
```

### Pandoc 互操作性

`toPandoc(doc : Doc, options : PandocRenderOptions) : Pandoc`

`PandocRenderOptions` 扩展 `Options` 与 `smartPunctuationMap`,具有窗体和默认值:

```js
{ non_breaking_space: " ",
  ellipses: "⋯",
  em_dash: "-",
  en_dash: "-",
  left_single_quote: "‘",
  right_single_quote: "’",
  left_double_quote: "“",
  right_double_quote: "”" };
```

使用实例:

```js
console.log(JSON.stringify(djot.toPandoc(djot.parse("- one\n- two\n"))));
```

`fromPandoc(pandoc : Pandoc, options : Options) : Doc`

使用实例:

```js
let ast = djot.fromPandoc(JSON.parse(pandocJSON));
```

### 过滤器

`applyFilter(node : Doc, filter : Filter)`

使用实例:

```js
const capitalizeFilter = () => {
  return {
           str: (e) => {
             e.text = e.text.toUpperCase();
           }
  };
};
let ast = djot.parse("Hi there `verbatim`");
djot.applyFilter(ast, capitalizeFilter);
```

过滤器是更改 AST 之间的 JavaScript 程序 解析和渲染。 它们可用于定制.

以下是过滤器的例子 使用文档中的全部内容文本 :

```js
// This filter capitalizes regular text, leaving code and URLs unaffected
return {
  str: (el) => {
    el.text = el.text.toUpperCase();
  }
}
```

这是打印您所有 URL 列表的过滤器 链接到文档中。 这个过滤器不会改变 文档;它只是将列表打印为 stderr.

```js
return {
  link: (el) => {
    process.stderr:write(el.destination + "\n")
  }
}
```

默认过滤器进行自下而上倒转;即 节点过滤器在孩子处理完毕后运行 . 不过,可以进行自上而下的旅行,甚至 在输入节点时运行单独的动作(处理前) (在处理儿童后)离开。 来 ,将节点的标记与含有 `enter` 和(或) `exit` 函数。 这个 `enter` 函数在我们穿越时运行 _输入_ 结点,在我们穿过它的子孙之前 `exit` 函数在我们穿越了节点的孩子之后运行. 对于一个自上而下转弯, 你会只是使用 `enter` 函数. 如果标签与函数直接相关, 如 第一个例子,它被视为一种“退出”功能.

以下过滤器将使用文本 内嵌着强调,但不是其他文字:

```js
// This filter capitalizes the contents of emph
// nodes instead of italicizing them.
let capitalize = 0;
return {
   emph: {
     enter: (e) => {
       capitalize = capitalize + 1;
     },
     exit: (e) => {
       capitalize = capitalize - 1;
       e.tag = "span";
     },
   },
   str: (e) => {
     if (capitalize > 0) {
       e.text = e.text.toUpperCase();
      }
   }
}
```

单个过滤器可能返回一个有多个表格的表格,这些表格将是 按顺序应用:

```js
// This filter includes two sub-filters, run in sequence
return [
  { // first filter changes (TM) to trademark symbol
    str: (e) => {
      e.text = e.text.replace(/\\(TM\\)/, "™");
    }
  },
  { // second filter changes '[]' to '()' in text
    str: (e) => {
      e.text = e.text.replace(/\\(/,"[").replace(/\\)/,"]");
    }
  }
]
```

目前为止我们所看到的过滤器 正在修改节点 改变其一种属性(`text`) (中文(简体) ). 有时我们想用另一种 节点,或有多个节点,或删除一个节点. 在这些 我们可以以 `return`。 。 。 . 如果返回一个 AST 节点, 它将替换元素 过滤器正在处理。 如果返回 AST 节点数组, 它们将被分解出来,以替换元素。 如果一个空 数组返回,该元素将被删除.

```js
// This filter replaces certain Symb nodes with
// formatted text.
const substitutions = {
  mycorp: [ { tag: "str", text: "My Corp" },
            { tag: "superscript",
              [ { tag: "str", text: "(TM)" } ] } ],
  myloc: { tag: "str", text: "Coyote, NM" }
  };
return {
  symb: (e) => {
    const found = substitutions[e.alias];
    if (found) {
      return found;
    }
  }
}
```

```js
// This filter replaces all Image nodes with their descriptions.
return {
  image: (e) => {
    return e.children;
  }
}
```

有可能阻止向一个节点的孩子转来转去, 拥有 `enter` 函数返回带有 属性 `stop`。内容 `stop` 将用作常规 返回值。 例如,这可用于防止 正在处理的脚注的内容:

```js
return {
 footnote: {
   enter: (e) => {
     return {stop: [e]};
    }
  }
}
```

### 获取版本

```js
djot.version : string
```

返回版本编号.

## 技术

Djot AST 格式最人能读取的文件 这是 [类型 定义](https://github.com/jgm/djot.js/blob/main/src/ast.ts)。 。 。 .

还有一个 [贾森 计划](https://github.com/jgm/djot.js/blob/main/djot-schema.json) 用于验证是否符合AST程序.

## 常见问题

### @djot/djot 是什么？

Djot 光标语言转换库

### 如何安装 @djot/djot？

在项目目录运行 npm install @djot/djot，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 djot，可以用 npx djot 直接运行。

### @djot/djot 支持 TypeScript 吗？

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

### @djot/djot 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

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

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

### @djot/djot 可以商用吗？

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

### @djot/djot 的下载量有多少？

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

### @djot/djot 还在维护吗？

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