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 逐层印证让每条参数、每个行为都有源码依据。一、命令总览SYNOPSISmarked是一个功能完整的 JavaScript Markdown 解析器专注于解析速度同时内置了多项 GFMGitHub 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 与 EXAMPLESmarked 支持三种输入来源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 --outputhello world.html -i in.md --no-breaks第一个示例等价于cat in.md | marked -i in.md out.html的管道形态适合与grep、sed等命令链式配合第四个示例展示了--optvalue的等号赋值写法这是由 bin/main.js 的getArg()实现的——当参数以--开头时会把--optval拆成--opt与val两部分处理。此外getArg()还支持短参数组合-abc会被拆解为-a -b -c依次解析因此诸如-tn同时开启 tokens 与 no-clobber这类紧凑写法也是合法的。三、全部命令行选项OPTIONS手册定义了如下参数每条都可以在 bin/main.js 的switch语句中定位到对应实现参数别名作用源码实现位置-o--output [file]指定输出文件不指定则写入 stdoutmain.js的output分支-i--input [file]指定输入文件否则使用最后一个位置参数再否则读 stdinmain.js的input分支-s--string [str]直接以字符串作为 Markdown 输入main.js的string分支-c--config [file]指定配置文件替代默认的~/.marked.json、~/.marked.js、~/.marked/index.jsmain.js的runConfig()-t--tokens输出 token 列表JSON而非 HTMLmain.js的tokens分支-n--no-clobber若输出文件已存在则拒绝覆盖并报错main.js的noclobber分支—--pedantic尽可能兼容 markdown.pl 的冷门行为不修复原始 Markdown 的缺陷落入默认分支映射到pedantic—--gfm开启 GitHub Flavored Markdown默认分支映射到gfm—--breaks开启 GFM 换行仅与--gfm搭配生效默认分支映射到breaks—--no-xxx上述任何选项的反向开关main.js的--no-前缀处理—--silent静默错误输出默认分支映射到silent-h--help显示帮助信息help()-v--version显示版本号version()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.jsconst 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。四、配置文件CONFIGURATION4.1 配置文件加载顺序与格式手册规定-c file可显式指定配置文件不指定时依次探测~/.marked.json、~/.marked.js、~/.marked/index.js命中第一个即停止。源码中的默认探测列表完整对应const defaultConfig [ ~/.marked.json, ~/.marked.js, ~/.marked/index.js, ];resolveFile()会把路径开头的~展开为用户主目录通过homedir()所以上述路径实际指向用户家目录下的配置文件。配置文件支持JSON 或 JSCommonJS/ESM两种格式加载逻辑在runConfig()中先尝试require()加载兼容 JSON 与 CommonJS若报ERR_REQUIRE_ESM改用import()动态加载 ESM 模块若模块带有default导出取其default值若导出值是函数则调用markedConfig(marked)把marked对象传入供其自行配置若是普通对象则执行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输出为pline1brline2/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 ALSOmarked 采用 MIT 许可证2018 年至今归 MarkedJS2011–2018 归 Christopher Jeffrey。手册 SEE ALSO 推荐的关联资料为markdown(1)Markdown 语法手册与nodejs(1)Node.js 手册。若需深入了解可继续阅读以下仓库资源CLI 完整实现bin/main.js、入口文件默认选项与类型定义src/defaults.ts、src/MarkedOptions.ts程序化 APIsrc/marked.tsCLI 行为测试test/unit/bin.test.js、配置文件测试夹具用法文档README.md、docs/USING_ADVANCED.md、docs/USING_PRO.md附快速参考速查表需求命令stdin 转 HTML 输出到文件cat in.md \| marked out.html渲染字符串echo hello *world* \| marked文件对文件marked -o out.html -i in.md --gfm等号形式传参marked --outputout.html -i in.md --no-breaks查看 token 树marked -t -i in.md不覆盖已有输出marked -n -o out.html -i in.md自定义配置文件marked -c ~/my-marked.js -i in.md反向开关marked -i in.md --no-gfm帮助 / 版本marked --help/marked --version【免费下载链接】markedA markdown parser and compiler. Built for speed.项目地址: https://gitcode.com/gh_mirrors/ma/marked创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 逐层印证让每条参数、每个行为都有源码依据。一、命令总览SYNOPSISmarked是一个功能完整的 JavaScript Markdown 解析器专注于解析速度同时内置了多项 GFMGitHub 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 与 EXAMPLESmarked 支持三种输入来源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 --outputhello world.html -i in.md --no-breaks第一个示例等价于cat in.md | marked -i in.md out.html的管道形态适合与grep、sed等命令链式配合第四个示例展示了--optvalue的等号赋值写法这是由 bin/main.js 的getArg()实现的——当参数以--开头时会把--optval拆成--opt与val两部分处理。此外getArg()还支持短参数组合-abc会被拆解为-a -b -c依次解析因此诸如-tn同时开启 tokens 与 no-clobber这类紧凑写法也是合法的。三、全部命令行选项OPTIONS手册定义了如下参数每条都可以在 bin/main.js 的switch语句中定位到对应实现参数别名作用源码实现位置-o--output [file]指定输出文件不指定则写入 stdoutmain.js的output分支-i--input [file]指定输入文件否则使用最后一个位置参数再否则读 stdinmain.js的input分支-s--string [str]直接以字符串作为 Markdown 输入main.js的string分支-c--config [file]指定配置文件替代默认的~/.marked.json、~/.marked.js、~/.marked/index.jsmain.js的runConfig()-t--tokens输出 token 列表JSON而非 HTMLmain.js的tokens分支-n--no-clobber若输出文件已存在则拒绝覆盖并报错main.js的noclobber分支—--pedantic尽可能兼容 markdown.pl 的冷门行为不修复原始 Markdown 的缺陷落入默认分支映射到pedantic—--gfm开启 GitHub Flavored Markdown默认分支映射到gfm—--breaks开启 GFM 换行仅与--gfm搭配生效默认分支映射到breaks—--no-xxx上述任何选项的反向开关main.js的--no-前缀处理—--silent静默错误输出默认分支映射到silent-h--help显示帮助信息help()-v--version显示版本号version()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.jsconst 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。四、配置文件CONFIGURATION4.1 配置文件加载顺序与格式手册规定-c file可显式指定配置文件不指定时依次探测~/.marked.json、~/.marked.js、~/.marked/index.js命中第一个即停止。源码中的默认探测列表完整对应const defaultConfig [ ~/.marked.json, ~/.marked.js, ~/.marked/index.js, ];resolveFile()会把路径开头的~展开为用户主目录通过homedir()所以上述路径实际指向用户家目录下的配置文件。配置文件支持JSON 或 JSCommonJS/ESM两种格式加载逻辑在runConfig()中先尝试require()加载兼容 JSON 与 CommonJS若报ERR_REQUIRE_ESM改用import()动态加载 ESM 模块若模块带有default导出取其default值若导出值是函数则调用markedConfig(marked)把marked对象传入供其自行配置若是普通对象则执行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输出为pline1brline2/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 ALSOmarked 采用 MIT 许可证2018 年至今归 MarkedJS2011–2018 归 Christopher Jeffrey。手册 SEE ALSO 推荐的关联资料为markdown(1)Markdown 语法手册与nodejs(1)Node.js 手册。若需深入了解可继续阅读以下仓库资源CLI 完整实现bin/main.js、入口文件默认选项与类型定义src/defaults.ts、src/MarkedOptions.ts程序化 APIsrc/marked.tsCLI 行为测试test/unit/bin.test.js、配置文件测试夹具用法文档README.md、docs/USING_ADVANCED.md、docs/USING_PRO.md附快速参考速查表需求命令stdin 转 HTML 输出到文件cat in.md \| marked out.html渲染字符串echo hello *world* \| marked文件对文件marked -o out.html -i in.md --gfm等号形式传参marked --outputout.html -i in.md --no-breaks查看 token 树marked -t -i in.md不覆盖已有输出marked -n -o out.html -i in.md自定义配置文件marked -c ~/my-marked.js -i in.md反向开关marked -i in.md --no-gfm帮助 / 版本marked --help/marked --version【免费下载链接】markedA markdown parser and compiler. Built for speed.项目地址: https://gitcode.com/gh_mirrors/ma/marked创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考