marked 命令行手册精读：CLI 参数、配置加载与编程接口全解析

marked 命令行手册精读：CLI 参数、配置加载与编程接口全解析

【免费下载链接】markedA markdown parser and compiler. Built for speed.项目地址: https://gitcode.com/gh_mirrors/ma/marked

导读

本文以项目自带的 man 手册 man/marked.1.md 为骨架，系统讲解 marked —— 一个以速度见长的 JavaScript Markdown 解析器与编译器 —— 的命令行（CLI）用法。你将掌握marked命令的完整参数体系（-o/-i/-s/-c/-t/-n等）、标准输入输出管道用法、三类默认配置文件加载机制，以及如何在 Node.js 中以Marked类编程式调用。全文将结合仓库源码 bin/main.js、src/defaults.ts 与 test/unit/bin.test.js 逐层印证，让每条参数、每个行为都有源码依据。

一、命令总览（SYNOPSIS）

marked是一个功能完整的 JavaScript Markdown 解析器，专注于解析速度，同时内置了多项 GFM（GitHub Flavored Markdown）特性。其命令行完整语法如下：

marked [-o <output file>] [-i <input file>] [-s <markdown string>] [-c <config file>] [--help] [--version] [--tokens] [--no-clobber] [--pedantic] [--gfm] [--breaks] [--no-etc...] [--silent] [filename]

从 package.json 可以看到，marked命令通过"bin": { "marked": "bin/marked.js" }暴露，安装依赖后即可直接在终端调用；man字段声明了./man/marked.1，说明构建时会由 package.json 的build:man脚本（marked-man man/marked.1.md > man/marked.1）把本文档编译成系统 man page，可通过man marked查看。运行环境要求 Node.js >= 20。

从入口源码 bin/marked.js 可以看出，命令启动后会将process.title设为marked并调用 bin/main.js 导出的main(process)完成参数解析与执行——参数解析的全部逻辑都集中在main.js的start()函数中，阅读该函数即可精确还原每个参数的行为。

二、输入输出方式（DESCRIPTION 与 EXAMPLES）

marked 支持三种输入来源：stdin 管道输入、文件输入（-i或位置参数）与字符串输入（-s）。从 bin/main.js 的getData()可以看到明确的优先级：-s字符串 >-i文件 > 位置参数文件（取最后一个）> stdin。

官方手册给出的四个经典示例：

# 从 stdin 读取，输出到 out.html cat in.md | marked > out.html # 直接渲染一行内联 Markdown 到 stdout echo "hello *world*" | marked # 显式指定输入输出文件，并开启 GFM marked -o out.html -i in.md --gfm # 用 --output= 等号形式指定输出文件，关闭 breaks marked --output="hello world.html" -i in.md --no-breaks

第一个示例等价于cat in.md | marked -i in.md > out.html的管道形态，适合与grep、sed等命令链式配合；第四个示例展示了--opt=value的等号赋值写法，这是由 bin/main.js 的getArg()实现的——当参数以--开头时会把--opt=val拆成--opt与val两部分处理。

此外getArg()还支持短参数组合：-abc会被拆解为-a -b -c依次解析，因此诸如-tn（同时开启 tokens 与 no-clobber）这类紧凑写法也是合法的。

三、全部命令行选项（OPTIONS）

手册定义了如下参数，每条都可以在 bin/main.js 的switch语句中定位到对应实现：

3.1 通用开关的映射机制（--gfm/--breaks/--pedantic/--silent）

手册中的--no-etc...描述的是"上述任意选项的反向形式"。其底层机制在 bin/main.js 的默认分支中：

• 凡是以--开头的未知参数，会被camelize()转换成驼峰键名（如--no-clobber变noclobber），并检查该键是否存在于marked.defaults中，不存在则忽略；
• 若参数以--no-开头，则把对应选项置为false（布尔选项）或null（非布尔选项）；
• 否则把布尔选项置为true，非布尔选项取下一个参数作为值。

也就是说，CLI 能识别的开关全集由默认选项集合决定。查看 src/defaults.ts 可知当前默认值为：async: false、breaks: false、gfm: true、pedantic: false、silent: false。注意：gfm默认即为true，因此手册示例中--gfm更多是显式声明；而--breaks需要gfm同时为真才生效（见 src/MarkedOptions.ts 中breaks的注释说明）。

3.2--tokens：查看中间产物

-t/--tokens不输出 HTML，而是输出 token 列表。实现位于 bin/main.js：

const html = tokens ? JSON.stringify(marked.lexer(data, options), null, 2) : await marked.parse(data, options);

它直接调用marked.lexer()（对应 src/Lexer.ts 的Lexer.lex）生成词法分析结果，并以缩进 2 格的 JSON 格式打印，适合调试解析过程或二次开发时研究 token 结构。此路径完全绕过了 Parser 渲染阶段，因此输出的是未经渲染的原始 token 树。

3.3--no-clobber：保护既有文件

-n/--no-clobber在输出前检查目标文件是否已存在，存在则抛错退出：

if (noclobber && await fileExists(output)) { throw Error("marked: output file '" + output + "' already exists, disable the '-n' / '--no-clobber' flag to overwrite\n"); }

该行为对应 test/unit/bin.test.js 中对各种参数组合的断言，例如输入文件不存在时 stderr 输出marked: <path>: No such file or directory且退出码为 1。

四、配置文件（CONFIGURATION）

4.1 配置文件加载顺序与格式

手册规定：-c <file>可显式指定配置文件；不指定时依次探测~/.marked.json、~/.marked.js、~/.marked/index.js，命中第一个即停止。源码中的默认探测列表完整对应：

const defaultConfig = [ '~/.marked.json', '~/.marked.js', '~/.marked/index.js', ];

resolveFile()会把路径开头的~展开为用户主目录（通过homedir()），所以上述路径实际指向用户家目录下的配置文件。

配置文件支持JSON 或 JS（CommonJS/ESM）两种格式，加载逻辑在runConfig()中：

1. 先尝试require()加载（兼容 JSON 与 CommonJS）；
2. 若报ERR_REQUIRE_ESM，改用import()动态加载 ESM 模块；
3. 若模块带有default导出，取其default值；
4. 若导出值是函数，则调用markedConfig(marked)，把marked对象传入供其自行配置；
5. 若是普通对象，则执行marked.use(markedConfig)注册为扩展。

当-c指定的文件不存在时，命令报错Cannot load config file '<path>'并以退出码 1 结束（见 test/unit/bin.test.js 的 "config not found" 用例）。

4.2 配置文件实战示例

仓库测试夹具 test/unit/fixtures/bin-config.js 给出了一个最小可用的 ESM 配置：

export default { breaks: true, };

配合命令marked -c bin-config.js -s "line1\nline2"，输出为<p>line1<br>line2</p>——breaks生效把换行转成<br>（对应 test/unit/bin.test.js 的-c用例断言）。仓库还验证了含#字符的配置路径（如bin-config#hash.js）也能正确加载。

更完整的对象式配置可包含 src/MarkedOptions.ts 定义的全部选项：async、breaks、extensions、gfm、hooks、pedantic、renderer、silent、tokenizer、walkTokens。而函数式配置则适合需要编程式定制 Renderer / Tokenizer / Hooks 的高级场景：

// ~/.marked.js —— 函数式配置示例 export default function (marked) { marked.use({ gfm: true, breaks: false, walkTokens(token) { // 对每个 token 做自定义处理 }, }); }

五、编程接口（程序化调用）

手册的 CONFIGURATION 一节同时说明：marked 除了 CLI，还可作为库在程序中调用。推荐方式是实例化Marked类再解析，避免影响全局默认实例：

import { Marked } from 'marked'; const marked = new Marked({ gfm: true }); marked.parse('*foo*');

从 src/Instance.ts（由 src/marked.ts 导出Marked）可知，new Marked(options)会基于 src/defaults.ts 的_getDefaults()建立独立默认配置；而直接使用marked.parse()走的是模块级单例markedInstance。源码注释建议：需要配置 hooks、renderer 或 tokenizer 时，应创建独立实例并通过Marked#use注册，而不是每次调用时传参。

若希望修改全局行为，可使用marked.setOptions(options)/marked.use(extension)，二者都会同步更新marked.defaults并调用changeDefaults()刷新全局默认值（src/defaults.ts、src/marked.ts）。CLI 之所以能识别--gfm、--breaks等开关，正是因为它直接读取了这套全局默认选项做键名校验。

六、错误处理与退出码

bin/main.js 将整体执行包在 try/catch 中：

• 文件不存在（ENOENT）时，向 stderr 输出marked: <path>: No such file or directory；
• 其他错误输出err.message；
• 任何错误均以退出码 1 结束；
• 正常完成则以退出码 0 结束。

--silent选项对应 src/MarkedOptions.ts 中 "渲染失败时显示 HTML 错误信息" 的开关语义；手册称其为"静默错误输出"，即渲染层报错时抑制错误信息的展示。

七、许可证与后续资源（LICENSE / SEE ALSO）

marked 采用 MIT 许可证：2018 年至今归 MarkedJS，2011–2018 归 Christopher Jeffrey。手册 SEE ALSO 推荐的关联资料为markdown(1)（Markdown 语法手册）与nodejs(1)（Node.js 手册）。

若需深入了解，可继续阅读以下仓库资源：

• CLI 完整实现：bin/main.js、入口文件
• 默认选项与类型定义：src/defaults.ts、src/MarkedOptions.ts
• 程序化 API：src/marked.ts
• CLI 行为测试：test/unit/bin.test.js、配置文件测试夹具
• 用法文档：README.md、docs/USING_ADVANCED.md、docs/USING_PRO.md

附：快速参考速查表

【免费下载链接】markedA markdown parser and compiler. Built for speed.项目地址: https://gitcode.com/gh_mirrors/ma/marked