开发工具【免费下载链接】remarkableMarkdown parser, done right. Commonmark support, extensions, syntax plugins, high speed - all in one. Gulp and metalsmith plugins available. Used by Facebook, Docusaurus and many others! Use https://github.com/breakdance/breakdance for HTML-to-markdown conversion. Use https://github.com/jonschlinkert/markdown-toc to generate a table of contents.项目地址https://gitcode.com/gh_mirrors/re/remarkable点击查看免费下载导读本文以 remarkable 文档 docs/parsing_core.md 为主体深入讲解负责全局语法处理的 Core rules核心规则——包括StateCore状态对象的数据结构、核心规则的函数签名与执行流程以及block、inline、references、abbr/abbr2、footnote_tail、replacements、smartquotes等预置规则各自承担的工作。读完本文你将掌握 remarkable 整个 Markdown 解析管线中“第一道工序”的内部机制能够理解parse()与parseInline()的行为差异并具备通过md.core.ruler增删、替换核心规则来扩展解析器的实践能力。一、Core rules 是什么全局解析的第一道工序remarkable 的解析管线由三类规则协作完成见 docs/parser.mdCore rules核心规则管理全局解析、或需要“整篇文档级视野”才能处理的 Markdown 语法例如引用链接reference links的定义收集、缩写abbreviation定义同时负责触发 Block rules 与 Inline rules 的执行。Block rules块级规则处理占据整行或多行的语法代码块、引用块、标题、hr 等详见 docs/parsing_block.md。Inline rules行内规则处理只占一行内部分文本的语法链接、加粗、强调、上下标、行内代码等详见 docs/parsing_inline.md。从源码看Core rules 之所以“独立成层”是因为它们具备两类 Block/Inline 规则不具备的能力跨块global操作references需要先扫描全文、把[label]: url title形式的定义统一收进env.references之后inline阶段行内链接才能解析——这天然需要“先于行内解析、且拥有整篇文档视野”的时机对 token 列表的整体改写abbr2会遍历所有inlinetoken 的children用正则把缩写包裹成abbr标签footnote_tail则会整体重排 token 流、在文档末尾追加脚注区块——这类“事后加工”也只有在核心层才合适。1.1 核心规则在解析管线中的位置调用链从 lib/index.js 的公开 API 开始Remarkable.prototype.parse function (str, env) { var state new StateCore(this, str, env); this.core.process(state); return state.tokens; }; Remarkable.prototype.render function (str, env) { env env || {}; return this.renderer.render(this.parse(str, env), this.options, env); };parse()创建StateCore后立即交给this.core.process(state)顺序执行全部核心规则产出的state.tokens再交给 Rendererlib/renderer.js生成 HTML。也就是说Core rules 是 Markdown → Tokens → HTML 这条管线中第一个真正执行解析逻辑的环节。二、StateCore核心规则唯一共享的状态对象2.1 函数签名一个核心规则就是一个只接收单个StateCore参数的函数function myCoreRule(state) { // 读取 / 修改 state.src、state.tokens、state.env ... }其定义与初始化代码位于 lib/index.jsfunction StateCore(instance, str, env) { this.src str; this.env env; this.options instance.options; this.tokens []; this.inlineMode false; this.inline instance.inline; this.block instance.block; this.renderer instance.renderer; this.typographer instance.typographer; }2.2 核心数据字段StateCore的核心数据与文档 docs/parsing_core.md 完全对应包括字段类型含义srcString解析器当前处理的完整 Markdown 字符串tokensArray由之前执行的核心规则陆续产出的 token 列表当前规则可读可写envObject命名空间化的 key-value 数据存储供核心规则之间交换数据如env.references、env.abbreviations、env.footnotesinlineModeBoolean标记解析器当前是否处于“仅行内模式”inline-mode only而非标准模式其余字段则是指向底层 remarkable 实例各组件instance.block、instance.inline、instance.renderer、instance.options等的引用供规则按需调用子解析器或读取选项。注意env的“命名空间化”含义它不是一层不变的普通对象而是各规则在其中以固定键名读写数据例如env.references、env.abbreviations键名前加:前缀以避免与Object.prototype成员冲突、env.footnotes。这正是核心规则之间跨阶段通信的机制。2.3 两种工作方式的规则文档明确指出核心规则分两类——直接处理src产出新 token或处理既有 token 列表产出新列表。从 lib/rules_core/ 的实现可以清楚看到这条分界线处理src的规则block把整篇src交给块级解析器、inline把每个inlinetoken 的content交给行内解析器处理 token 列表的规则references、abbr从段落inlinetoken 的内容中剥离定义、abbr2重写inlinetoken 的children、footnote_tail过滤并重排state.tokens、replacements与smartquotes遍历改写inlinetoken children 中的文本。三、核心规则的注册与执行Ruler 链与 parser_core.js3.1 预置规则及其注册顺序lib/parser_core.js 用Ruler注册了全部预置核心规则顺序即执行顺序var _rules [ [ block, block ], [ abbr, abbr ], [ references, references ], [ inline, inline ], [ footnote_tail, footnote_tail ], [ abbr2, abbr2 ], [ replacements, replacements ], [ smartquotes, smartquotes ], ];Core.prototype.processlib/parser_core.js按注册顺序逐一调用Core.prototype.process function (state) { var rules this.ruler.getRules(); for (var i 0, l rules.length; i l; i) { rulesi; } };顺序不是随意的而是环环相扣的依赖关系block必须先跑它把src解析成块级 token含所有inline内容 tokenabbr、references紧随其后趁段落内容还以原始 Markdown 文本形式保存在inlinetoken 的content中把*[abbr]: desc和[label]: url定义剥离出来写入envinline接着把每个inlinetoken 的 content 递归解析为children此时行内链接才能借助env.references命中已收集的定义footnote_tail、abbr2、replacements、smartquotes最后执行基于已成型、可遍历的 token 树做整体改写与文本美化。3.2 Ruler核心规则链的管理机制规则链由 lib/ruler.js 中的Ruler类实现这是整个 remarkable 三套规则core/block/inline共用的注册与调度基础设施。与核心规则相关的常用 API 有API作用ruler.push(name, fn, options)在链尾追加规则ruler.at(name, fn, options)按名称替换某条规则名称不存在则抛错ruler.before(beforeName, name, fn, options)/ruler.after(afterName, name, fn, options)在指定规则前后插入规则ruler.enable(list, strict)/ruler.disable(list)启用/禁用规则stricttrue时先禁用全部再只启用列表中的规则ruler.getRules(chainName)返回按顺序排列的规则函数数组每条规则在内部表示为{ name, enabled, fn, alt }。altalternative chains用于构建命名规则链getRules()返回默认主链而带alt名称的规则会同时出现在对应命名链中——这使得“在某一类语法上应用规则”成为可能。注册后调用链被缓存__cache__任何增删改操作都会清空缓存以便下次重新编译。3.3 用 Ruler 扩展核心层由于Remarkable实例将核心解析器暴露为md.core开发者可以像操作插件一样调整核心规则var Remarkable require(remarkable); var md new Remarkable(); // 在 references 之前插入一条自定义核心规则 md.core.ruler.before(references, my_rule, function (state) { // 自定义全局处理读取 state.src / 改写 state.env / 增删 state.tokens });自定义核心规则必须遵守 StateCore 的约定直接读state.src、state.env通过state.tokens产出或改写 token并通过state.env与其它规则交换数据。与 Block/Inline 规则不同核心规则没有checkMode参数也不返回布尔值——它要么完成任务要么不做任何事。四、block与inline核心层的两个调度枢纽文档强调“最重要的预置核心规则是block和inline”它们负责调用 Block/Inline 子解析器。看 lib/rules_core/block.js 的实现export default function block(state) { if (state.inlineMode) { state.tokens.push({ type: inline, content: state.src.replace(/\n/g, ).trim(), level: 0, lines: [ 0, 1 ], children: [] }); } else { state.block.parse(state.src, state.options, state.env, state.tokens); } }而 lib/rules_core/inline.js 遍历既有 token 中的每个inline类型 token将其content交给行内解析器填充childrenexport default function inline(state) { var tokens state.tokens, tok, i, l; for (i 0, l tokens.length; i l; i) { tok tokens[i]; if (tok.type inline) { state.inline.parse(tok.content, state.options, state.env, tok.children); } } }4.1inlineMode与parseInline()/renderInline()inlineMode标志正是由公开 API 的两种入口驱动的lib/index.jsRemarkable.prototype.parseInline function (str, env) { var state new StateCore(this, str, env); state.inlineMode true; this.core.process(state); return state.tokens; }; Remarkable.prototype.renderInline function (str, env) { return this.renderer.render(this.parseInline(str, env), this.options, env); };当inlineMode true时block规则不再调用块级解析器而是直接把整篇src换行被替换为空格并 trim压成一个孤立的inlinetokenlib/rules_core/block.jsreferences与abbr规则会直接return跳过定义收集lib/rules_core/references.js、lib/rules_core/abbr.js。因此renderInline(**bold** and *em*)不会包p标签适合渲染不构成独立段落的一小段文本。五、逐个拆解预置核心规则都做了什么5.1references收集引用链接定义这是“需要全局视野”的典型代表。Markdown 支持[text][label]引用式链接其定义[label]: /url title可以出现在文档任意段落中。references规则lib/rules_core/references.js在行内解析前扫描所有形如paragraph_open → inline → paragraph_close的三元组从段落inlinetoken 的原始内容中反复调用parseReference()剥离定义state.env.references state.env.references || {}; // 对每个独立段落 inline token content tokens[i].content; while (content.length) { pos parseReference(content, state.inline, state.options, state.env); if (pos 0) { break; } content content.slice(pos).trim(); } tokens[i].content content; if (!content.length) { tokens[i - 1].tight true; // 整段都是定义时标记段落为 tight tokens[i 1].tight true; }parseReference()的解析步骤对应 lib/rules_core/references.js首字符必须是[且整串中存在]:否则直接返回-1用parseLinkLabellib/helpers/parse_link_label.js解析[label]并确认后跟:跳过空白后调用parseLinkDestinationlib/helpers/parse_link_destination.js解析目标地址再跳过空白可选地调用parseLinkTitlelib/helpers/parse_link_title.js解析title定义行必须以换行收尾保证“一整行”约束否则视为格式错误返回-1用normalizeReferencelib/helpers/normalize_reference.js规范化 label 后写入env.references[label] { title, href }已存在的 label 不会被覆盖。收集完成后后续inline阶段的行内链接规则便能从env.references中查到定义。这也解释了为什么references必须排在inline之前。5.2abbr解析缩写定义缩写定义使用扩展语法*[abbr]: description。abbr规则lib/rules_core/abbr.js与references结构几乎一致同样只扫描独立段落调用parseAbbr()剥离定义并写入env.abbreviations。parseAbbr()的约束lib/rules_core/abbr.js必须以*[开头ASCII0x2A0x5B且存在]:定义标题必须位于同一行扫描到\n为止标题不能为空键名以:前缀存储env.abbreviations[: label]规避与Object.prototype成员如constructor、toString冲突同名的已存在定义不会被覆盖。例如 test/fixtures/remarkable/abbr.txt 中的用例*[HTML]: Hyper Text Markup Language *[W3C]: World Wide Web Consortium The HTML specification is maintained by the W3C.渲染结果为去掉定义行、正文中命中缩写处包上abbr title...pThe abbr titleHyper Text Markup LanguageHTML/abbr specification is maintained by the abbr titleWorld Wide Web ConsortiumW3C/abbr./p5.3abbr2把缩写包裹成abbr标签abbr只负责“收集定义”真正把正文中的缩写替换为abbr的是紧随其后的abbr2规则lib/rules_core/abbr2.js若env.abbreviations为空则直接返回首次运行时基于所有已收集缩写构造一个全局正则env.abbrRegExp形如(^|[分隔符])(abbr1|abbr2|...)([分隔符]|$)其中较长的缩写排在前面sort(function (a, b) { return b.length - a.length; })以保证“最左最长优先匹配”逆序遍历每个inlinetoken 的children从末尾向前避免插入新 token 后位置偏移对texttoken 执行正则将命中片段拆分为abbr_open → text → abbr_close的 token 序列。正因为先按长度降序排列JS HTTP这类包含更短缩写HTTP的复合缩写才能优先整体匹配见 test/fixtures/remarkable/abbr.txt 中Intersecting abbreviations一节。最终的abbr title...HTML 由 lib/rules.js 的abbr_open/abbr_close渲染规则输出。5.4footnote_tail在文档末尾组装脚注区块脚注由块级规则footnotelib/rules_block/footnote.js与行内规则footnote_ref、footnote_inline负责收集而footnote_taillib/rules_core/footnote_tail.js负责在核心层收尾时统一组装若env.footnotes不存在则直接返回先用filter把footnote_reference_open/close包裹的内容即内联脚注正文从 token 流中摘出暂存到refTokens[: label]若env.footnotes.list为空则提前返回否则在state.tokens末尾依次追加footnote_block_open → (footnote_open → 段落/引用内容 → 若干个 footnote_anchor → footnote_close)* → footnote_block_close其中footnote_anchor数量取决于list[i].count被引用的次数最少 1 个。渲染出的典型脚注结构见 test/fixtures/remarkable/footnotes.txt为hr classfootnotes-sepsection classfootnotesol classfootnotes-list包裹的编号列表具体 HTML 模板定义在 lib/rules.js。5.5replacements语言中立的排版替换replacementslib/rules_core/replacements.js仅在state.options.typographer为true时生效lib/configs/default.js 中默认typographer: false。它遍历所有inlinetoken 的text子 token 做如下替换(c)→©、(r)→®、(p)→§、(tm)→™大小写不敏感lib/rules_core/replacements.js连续两个及以上句点..、...、....→ 省略号…但?...会被规整为?..见 lib/rules_core/replacements.js连续逗号、????/!!!!类重复标点压缩---→ em-dash—、--→ en-dash–。源码顶部还留有 TODO 注释分数 1/2 → ½、乘号 2 x 4 → 2 × 4说明这类替换规则仍在演进中。注意这些替换默认不开启属于 typographer 模式的组成部分。5.6smartquotes智能引号同样由typographer: true激活的smartquoteslib/rules_core/smartquotes.js把直引号与转换为成对的排版引号用PUNCT_RE /[-\s()\[\]]/判断某位置是否处于单词内部利用一个局部栈记录尚未闭合的引号含 token 索引、字符位置、单/双引号类型与嵌套 level遇到可闭合引号时回溯栈找匹配项成对替换单词中间的单引号被替换为右单引号’撇号语义如dont→don’t引号字符对来自state.options.quoteslib/configs/default.js 默认quotes: “”‘’注释还说明俄语可设为«»、德语可设为„“等。其渲染规则同样定义在 lib/rules.js 的text规则中转义后输出。六、配置预设如何裁剪核心规则remarkable 三种预设lib/configs/对核心规则做了不同的启用裁剪通过Ruler.enable(list, true)的 strict 模式实现lib/index.js预设启用的核心规则说明defaultlib/configs/default.jsblock、inline、references、replacements、smartquotes、references、abbr2、footnote_tail注意注册表中还有abbr但 default 预设的启用列表里未包含abbr因此默认配置下缩写定义不会被收集fulllib/configs/full.js不限制任何规则core: {}全部核心规则均处于启用状态缩写、脚注、typographer 全部可用commonmarklib/configs/commonmark.jsblock、inline、references、abbr2严格 CommonMark 行为禁用脚注与 typographer 相关规则这里有一个值得注意的细节default预设的启用列表中abbr2虽然出现但负责收集定义的abbr并未启用因此默认预设下abbr2因env.abbreviations为空而直接返回lib/rules_core/abbr2.js不会产生副作用。若需缩写功能应使用full预设或显式调用var md new Remarkable(full);七、实践验证核心规则的行为7.1 用 renderInline 验证 inlineModevar Remarkable require(remarkable); var md new Remarkable(); md.render(**bold**\n\nnext paragraph); // pstrongbold/strong/p\npnext paragraph/p\n md.renderInline(**bold**\n\nnext); // strongbold/strong next ← 无 p 包裹换行被空格替代7.2 观察 env 的跨规则数据交换核心规则之间的通信完全依赖env这也是理解整个解析器的关键references写入env.references行内links规则消费它abbr写入env.abbreviationsabbr2消费它。例如var md new Remarkable(full); md.render(*[HTML]: Hyper Text Markup Language\n\nHTML is great); // pabbr titleHyper Text Markup LanguageHTML/abbr is great/p7.3 测试用例参考仓库测试套件覆盖了全部核心规则行为可作为扩展核心规则时的对照基准缩写 test/fixtures/remarkable/abbr.txt脚注 test/fixtures/remarkable/footnotes.txt智能引号与 typographer test/fixtures/remarkable/smartquotes.txt、test/fixtures/remarkable/typographer.txt引用链接 test/fixtures/commonmark/spec.txtCommonMark 规范中 reference links 一节八、小结Core rules 是 remarkable 解析管线的“总调度与总加工层”StateCore承载了src、tokens、env、inlineMode四个关键状态block与inline两个枢纽规则把解析任务分别下发给块级与行内子解析器references、abbr/abbr2、footnote_tail等规则则利用核心层的全局视野完成引用收集、缩写替换、脚注收尾这类跨块工作replacements与smartquotes提供可选的 typographer 排版美化。理解这层机制是深入定制 remarkable无论是替换默认规则、插入自定义全局处理还是理解render与renderInline差异的第一块基石。想继续深入可依次阅读 docs/parser.mdtoken 模型与三类规则的定位、docs/parsing_block.md 与 docs/parsing_inline.md另两类规则的签名与状态对象再对照 lib/parser_core.js、lib/ruler.js 与 lib/rules_core/ 的完整实现。赞分享开发工具【免费下载链接】remarkableMarkdown parser, done right. Commonmark support, extensions, syntax plugins, high speed - all in one. Gulp and metalsmith plugins available. Used by Facebook, Docusaurus and many others! Use https://github.com/breakdance/breakdance for HTML-to-markdown conversion. Use https://github.com/jonschlinkert/markdown-toc to generate a table of contents.项目地址https://gitcode.com/gh_mirrors/re/remarkable点击查看免费下载相关推荐Remarkable 解析规则Parsing Rules完全指南Core / Block / Inline 三类规则与 Token 体系剖析Remarkable 解析规则Parsing Rules完全指南Core / Block / Inline 三类规则与 Token 体系剖析 本篇指南以开发工具SQLFluff 规则参考Rules Reference完全指南Core 核心规则、规则分组与索引体系SQLFluff 规则参考Rules Reference完全指南Core 核心规则、规则分组与索引体系 本文以 SQLFluff 官方文档中的 Rules代码质量Lint格式化静态分析开发工具7步实战秘籍深度参与Czkawka多平台文件清理工具共建7步实战秘籍深度参与Czkawka多平台文件清理工具共建 你是否曾为电脑中堆积的重复文件而烦恼是否渴望参与一个真正实用的开源工具开发Czkawka项目为你桌面应用上一篇小红书图片打不开HEIC和WEBP一秒转JPEGXHS-Downloader三步搞定下一篇GetQzonehistory备份神器亲测5分钟把QQ空间十年说说完整搬回本地创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考