# @code-dot-org/redactable-markdown 中文文档 规范地址：https://npmcn.com/package/%40code-dot-org/redactable-markdown/ 版本：0\.10\.0 npm 元数据更新时间：2026-07-31T19:42:27.215Z 中文译文更新时间：2026-11-10T06:04:25.487Z 软件包许可：SEE LICENSE IN LICENSE 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40code-dot-org/redactable-markdown 原文对照：https://npmcn.com/package/%40code-dot-org/redactable-markdown/?lang=original 源码仓库：https://github.com/code-dot-org/redactable-markdown ## 关键信息（来自 npm 元数据） - 包体积（解压后）：442 kB，27 个文件 - 模块格式：CommonJS - TypeScript 类型：未声明 - 运行依赖：13 个 - 首次发布：2018-05-31T21:27:22.985Z - 最新版本发布：2024-04-05T19:06:06.707Z - 近 30 天下载量：6399（2026-10-10 至 2026-11-08，npm 官方下载统计） - 已发布版本数：22（近 12 个月 0 个） ## 中文简介 [![Build Status](https://github.com/code-dot-org/redactable-markdown/actions/workflows/continuous-integration-tests.yml/badge.svg?branch=master)](https://github.com/code-dot-org/redactable-markdown/actions/workflows/continuous-integration-tests.yml) \[没有 ## 安装 ```sh npm install @code-dot-org/redactable-markdown ``` 也可以使用：`pnpm add @code-dot-org/redactable-markdown`、`yarn add @code-dot-org/redactable-markdown`、`bun add @code-dot-org/redactable-markdown` ## README # 可修改标记 [![Build Status](https://github.com/code-dot-org/redactable-markdown/actions/workflows/continuous-integration-tests.yml/badge.svg?branch=master)](https://github.com/code-dot-org/redactable-markdown/actions/workflows/continuous-integration-tests.yml) [![npm version](https://img.shields.io/npm/v/@code-dot-org/redactable-markdown.svg)](https://www.npmjs.com/package/@code-dot-org/redactable-markdown) 用于解析和翻译 code.org 使用的 markdown 修改版的工具 ## 概览 标准操作可以做 在一块标记下的内容是 渲染;将下标内容解为可以理解的行为 结构和将结构编译出(通常是)HTML. 为了更好地翻译减记和扩展CDO减记,我们添加 两项新行动: ## 编辑 校正是将下标内容解为可以理解的过程 格式,然后将结构编译为带有一些值的缩放 删除并简化一些语法. 例如标准下标链接和图像: ``` [a link](http://example.com) ![an image](http://example.com/img.jpg) ``` 在编辑过程中删除其url 和href 值,如果是的话 图像 `!` 字符也被删除;将其简化为: ``` [a link][0] [an image][1] ``` 结果是,翻译们接触到的只是原件中的这些部分 内容,我们实际上希望他们翻译。 这表示我们最终 可以做的工作少得多 核实 翻译没有打破任何东西或 引入恶意内容 在翻译的结尾 意味着他们需要 更别担心要确定字符串的哪个部分 并且不应对变化负责. 一般来说,内容总是被修改为两组方括号,第一组是: 附上我们想向翻译和 附加一个我们用来关联编辑内容的唯一数字ID 与恢复过程中的原始数据一起返回. ### 其他例子 #### Div 类 CDO Markdown推出的新语法, diviclass 是一个很好的例子 "堵"删". Divclass 允许我们用 divs 来包装一些内容 他们看起来就像: ``` [some-class-name] Inner content - content can contain - *whatever* __syntax__ we generally support - Including [things that get redacted](http://example.com) [/some-class-name] ``` 内容将修改为: ``` [][0] Inner content - content can contain - _whatever_ **syntax** we generally support - Including [things that get redacted][1] [/][0] ``` #### 词汇定义 最初引入的新语法用于支持课程建设(但自 扩展为 Dashboard 的 Markdown 预处理器,词汇定义为 a 一个简单的线性编辑 略为复杂的例子 恢复过程。 Vocablink 用于嵌入复合体的定义 在一个段落中,它们看起来是: ``` In particular we are interested in developing a more robust [v protocol/coursea/2021] for sending a list of numbers over the internet. ``` 内容将修改为: ``` In particular we are interested in developing a more robust [protocol][0] for sending a list of numbers over the internet. ``` ## 恢复 编辑内容后,将编辑内容发去翻译后, 我们会拿回经编辑的内容的翻译版本。 然后我们结合 创建已恢复的翻译版本 原始内容. 例如标准下标链接和图像: ``` [a link](http://example.com) ![an image](http://example.com/img.jpg) ``` 在被编辑和翻译后,可能会像: ``` [un linke][0] [une image][1] ``` 然后与原始内容重新组合,以产生: ``` [un linke](http://example.com) ![une image](http://example.com/img.jpg) ``` 请注意,每个被编辑的内容的独特识别符都使我们能够 处理翻译过程中可能引入的任何重排。 对于 实例, ``` A [black](http://example.com/black) [cat](http://example.com/cat) ``` 将修改为 ``` A [black][0] [cat][1] ``` 然后翻译为: ``` Un [chat][1] [noir][0] ``` 然后恢复到 ``` Un [chat](http://example.com/cat) [noir](http://example.com/black) ``` ## 插件 定义新建或已存在的 语法,简单地创建一个插件. 插件以备注分隔插件开头 表格中描述的 [扩展 解析器](https://github.com/remarkjs/remark/tree/master/packages/remark-parse#extending-the-parser), (中文(简体) ), 和实例 [在源树上](https://npmcn.com/src/plugins/parser/)。 。 。 . ### 基本编辑示例 例如,让我们在 `mention` 注释页中的插件 实例。 我们从头开始 `mention.js` 从这个例子: ```javascript module.exports = mentions; function mentions() { var Parser = this.Parser; var tokenizers = Parser.prototype.inlineTokenizers; var methods = Parser.prototype.inlineMethods; /* Add an inline tokenizer (defined in the following example). */ tokenizers.mention = tokenizeMention; /* Run it just before `text`. */ methods.splice(methods.indexOf('text'), 0, 'mention'); } tokenizeMention.notInLink = true; tokenizeMention.locator = locateMention; function tokenizeMention(eat, value, silent) { var match = /^@(\w+)/.exec(value); if (match) { if (silent) { return true; } return eat(match[0])({ type: 'link', url: 'https://social-network/' + match[1], children: [{type: 'text', value: match[0]}] }); } } function locateMention(value, fromIndex) { return value.indexOf('@', fromIndex); } ``` 首先,从解析符号中提取有意义的数据的逻辑 从从提取的数据中构建节点的逻辑中: ```diff diff --git a/mention.js b/mention.js index c87085f..12b67ed 100644 --- a/mention.js +++ b/mention.js @@ -23,14 +29,19 @@ function tokenizeMention(eat, value, silent) { return true; } - return eat(match[0])({ - type: 'link', - url: 'https://social-network/' + match[1], - children: [{type: 'text', value: match[0]}] - }); + var add = eat(match[0]); + return createMention(add, match[1], match[0]); } } function locateMention(value, fromIndex) { return value.indexOf('@', fromIndex); } + +function createMention(add, name, text) { + return add({ + type: 'link', + url: 'https://social-network/' + name, + children: [{type: 'text', value: text}] + }); +} ``` 然后,有条件地创建一个 `redaction` 节点而不是理想的正则 编辑模式时的节点( 更多关于 `redaction` 节点 [这里](https://github.com/code-dot-org/redactable-markdown/blob/29c64b3c9e736e28746e6a8627b57c8cc3f0dcc0/src/plugins/process/restorationRegistration.js#L8-L15): 请注意,编辑节点只需要包含一个 独一无二 `redactionType` 标识符,以及重建 节点. ```diff diff --git a/mention.js b/mention.js index 7a6fc91..08f1bf0 100644 --- a/mention.js +++ b/mention.js @@ -1,10 +1,15 @@ module.exports = mentions; +var redact; + function mentions() { var Parser = this.Parser; var tokenizers = Parser.prototype.inlineTokenizers; var methods = Parser.prototype.inlineMethods; + /* Make the Parser's redact option visible to the tokenizer */ + redact = Parser.prototype.options.redact; + /* Add an inline tokenizer (defined in the following example). */ tokenizers.mention = tokenizeMention; @@ -24,7 +29,19 @@ function tokenizeMention(eat, value, silent) { } var add = eat(match[0]); - return createMention(add, match[1], match[0]); + var name = match[1]; + var text = match[0]; + + if (redact) { + return add({ + type: 'redaction', + redactionType: 'mention', + name: name, + text: text + }); + } + + return createMention(add, name, text); } } ``` 最后,为指定的编辑类型添加一个恢复方法,使用 新同位化节点创建逻辑. ```diff diff --git a/mention.js b/mention.js index 08f1bf0..beb01ca 100644 --- a/mention.js +++ b/mention.js @@ -6,6 +6,11 @@ function mentions() { var Parser = this.Parser; var tokenizers = Parser.prototype.inlineTokenizers; var methods = Parser.prototype.inlineMethods; + var restorationMethods = Parser.prototype.restorationMethods; + + restorationMethods.mention = function (add, node) { + return createMention(add, node.name, node.text); + } /* Make the Parser's redact option visible to the tokenizer */ redact = Parser.prototype.options.redact; ``` 我们现在可以重新编辑和恢复 `@` 提及: ```bash $ echo "Hello @example" > source.md $ redact source.md -p mention.js | tee redacted.md Hello [][0] $ sed 's/Hello/Bonjour/' redacted.md | tee translated.md Bonjour [][0] $ restore -s source.md -r translated.md -p mention.js Bonjour [@example](https://social-network/example) ``` ### 高级编辑示例 我们还可以选择允许修改和恢复进程 更改已解析文本的处理方式. 说我们希望编辑版 基本例子曝光 `@` 名称 例如: ``` Hello [@example][0] ``` 并将修改后的文字反映于 生成链接, 如 : ``` Bonjour [@exemple][0] > Bonjour [@exemple](https://social-network/example) ``` 为了做到这一点,我们首先移动 `text` 从属性的值 `redaction` 节点为全 `text` 子节点 : ```diff diff --git a/mention.js b/mention.js index beb01ca..af09cc5 100644 --- a/mention.js +++ b/mention.js @@ -42,7 +42,11 @@ function tokenizeMention(eat, value, silent) { type: 'redaction', redactionType: 'mention', name: name, - text: text + children: [{ + type: 'text', + value: text + }] }); } ``` 然后,我们扩大修复方法 利用可选 `content` 参数,其中将包含文本内容的修改版本. ```diff diff --git a/mention.js b/mention.js index beb01ca..af09cc5 100644 --- a/mention.js +++ b/mention.js @@ -8,8 +8,8 @@ function mentions() { var methods = Parser.prototype.inlineMethods; var restorationMethods = Parser.prototype.restorationMethods; - restorationMethods.mention = function (add, node) { - return createMention(add, node.name, node.text); + restorationMethods.mention = function (add, node, content) { + return createMention(add, node.name, content); } /* Make the Parser's redact option visible to the tokenizer */ ``` 结果: ```bash $ echo "Hello @example" > source.md $ redact source.md -p mention.js | tee redacted.md Hello [@example][0] $ sed -e 's/Hello/Bonjour/' -e 's/example/exemple/' redacted.md | tee translated.md Bonjour [@exemple][0] $ restore -s source.md -r translated.md -p mention.js Bonjour [@exemple](https://social-network/example) ``` ## 常见问题 ### @code-dot-org/redactable-markdown 是什么？ \[没有 ### 如何安装 @code-dot-org/redactable-markdown？ 在项目目录运行 npm install @code-dot-org/redactable-markdown，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 parse、redact、render、restore、normalize，可以用 npx parse 直接运行。 ### @code-dot-org/redactable-markdown 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/code-dot-org\_\_redactable-markdown 是否存在。 ### @code-dot-org/redactable-markdown 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @code-dot-org/redactable-markdown 可以商用吗？ @code-dot-org/redactable-markdown 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。 ### @code-dot-org/redactable-markdown 的下载量有多少？ 根据 npm 官方下载统计，@code-dot-org/redactable-markdown 在 2026/10/10 – 2026/11/08 这 30 天内被下载 6,399 次，日均约 213 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @code-dot-org/redactable-markdown 还在维护吗？ 最新版本 0\.10\.0 发布于 2024/04/06（2 年前）；至今共发布 22 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/06/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。