开发工具CLI后端【免费下载链接】saplingA Scalable, User-Friendly Source Control System.项目地址https://gitcode.com/gh_mirrors/sa/sapling点击查看免费下载导读sapling-output-plugin是 Sapling 网站基于 Docusaurus MDX内置的一个 remark/MDX 插件它让文档作者可以写出只含命令、不含输出的示例代码块with-output代码块并由真实运行的 Sapling CLI 在构建期自动补全输出结果。本文将以 website/src/plugins/sapling-output/README.md 为骨架结合插件源码、debugruntest命令实现和站点配置讲清它的使用语法、内部执行链路、运行依赖以及本地调试方法读完即可在自己的文档项目中复刻这套“命令输出自动生成”的写作模式。一、插件定位在文档构建期“跑出”示例输出在传统技术文档写作中命令示例的输出往往是作者手工复制粘贴的容易随版本迭代而失真。sapling-output-plugin解决了这个问题它在文档静态构建阶段把 MarkdownMDX里标记为with-output的代码块转换成 Sapling 自身的.t测试文件交给真实 CLI 执行再把执行后补全的输出回填到代码块中渲染出来。从站点配置可以看出它的接入位置——website/docusaurus.config.js 中它作为 Docusaurus docs 的remarkPlugins之一注册remarkPlugins: [ [require(remark-github).default, {repository: facebook/sapling}], require(sapling-output-plugin), ],插件本质是一个把 MDX AST 中所有lang with-output的code节点收集起来、异步改写其value的 remark 转换器见 website/src/plugins/sapling-output/src/index.ts。它借助unist-util-visit遍历语法树并用Promise.all并行处理所有待补全的代码块。二、使用语法with-output代码块与隐藏区1. 最简单的用法在任意 MDX 文档中把语言标记写成with-outputwith-output $ echo a 构建渲染后插件会运行这条命令并把真实输出补在下方页面最终显示为$ echo a a2. 语法来源.t测试的简化版with-output的语法与 Sapling 集成测试使用的.t测试文件高度一致语法解析器见 eden/scm/sapling/testing/init.py区别在于在.t文件中每条命令前需要两个空格前缀而with-output代码块不需要。插件会在内部把每一行自动加上 前缀转成标准的.t输入对应源码processInput中的逻辑website/src/plugins/sapling-output/src/index.ts。3. 用# hide begin/# hide end隐藏准备命令文档作者经常需要在示例前做初始化又不希望这些准备命令出现在读者面前。插件支持用# hide begin和# hide end圈定隐藏区域例如with-output # hide begin $ sl init repo $ cd repo $ touch a b # hide end $ sl add a $ sl st 渲染结果为准备命令被隐去只剩读者关心的命令和输出$ sl add a $ sl st A a ? b注意# hide begin/# hide end之间的命令仍会真实执行只是其命令行不回显、其输出也不参与渲染。三、内部原理从 MDX 到.t再到回填输出插件的核心实现在 website/src/plugins/sapling-output/src/index.ts整个流程可分为四步。1. 注入示例运行环境头EXAMPLE_HEADER插件会在每个示例最前面插入一段被# hide begin/# hide end包裹的环境准备脚本源码第 18-35 行包括向$HGRCPATH追加[ui]、[init]、[templatealias]配置例如设置prefer-gitfalse以及sl_difflink、github_pull_request_number、github_pr_state、github_pull_request_status_check_rollup等模板别名使示例中的 PR 相关模板输出与真实环境一致导出TEST_PROD_CONFIGS1以加载生产环境模板导出HGCOLORS16、SL_COLORS16强制 16 色输出保证渲染出的彩色终端文本稳定可预期。2. 生成临时.t文件并调用debugruntest --fixrenderExample源码第 116-146 行会在系统临时目录下创建前缀为mdx-sapling-output的临时目录把处理后的示例写入example.t然后调用sl debugruntest -q --fix example.t其中--fix等价于-i表示“按实际输出更新测试文件”。执行结束后插件重新读回被补全的example.t这就是渲染输出。调用失败时退出码1表示“至少有一处输出不匹配”这是预期结果会被吞掉其他错误码才会抛出。3. 清理输出processOutput读回的.t输出需要还原为文档友好的形式源码第 72-93 行删除每行开头的两个空格前缀.t的输出行标记移除# hide相关行以及# hide begin到# hide end之间的整段内容去掉文件开头的空行。4. 颜色支持终端颜色 ANSI 序列会被映射为 HTML 颜色。源码中内置了 Windows Console 的 Campbell 调色板COLORS常量第 95-113 行把\x1b[38;5;Nm之类的颜色码转换为对应的十六进制色值从而在页面上还原命令输出的彩色效果如A、?等状态标记的颜色区分。5. CLI 选择SL环境变量默认情况下插件调用sl命令若希望指向特定路径的 Sapling 可执行文件可设置环境变量SL源码第 183-185 行SL/path/to/sl yarn build四、运行依赖debugruntest命令详解插件正常运行的前提是系统中存在可用的 Sapling CLIsl。它依赖的debugruntest别名debugrt、.t是 Sapling 内置的.t测试执行命令定义于 eden/scm/sapling/commands/debug.pysl debugruntest [OPTION]... [TEST]... -i, --fix 更新测试以匹配实际输出 -j, --jobs 并行运行的 job 数 -x, --ext 要导入的扩展模块 -d, --direct 不使用隔离直接运行 --record 记录测试状态其中norepoTrue意味着该命令可在任意目录执行无需处于仓库内——这正是插件能在文档构建期自由生成临时.t文件并运行的前提。关于.t格式与debugruntest的更多细节与run-tests.py的差异、扩展语法、Pythondoctest 块等可参考 eden/scm/sapling/testing/init.py。例如debugruntest支持 Python doctest 风格的块——站点中 zstdelta 文档 就大量使用了这一特性直接在with-output代码块里写交互式 Python 代码并让插件补全运行结果。五、开发与调试指南1. 插件工程结构插件是一个独立的 TypeScript 工程目录结构如下详见 website/src/plugins/sapling-output/package.jsonsrc/index.ts插件全部实现CommonJS 导出 remark 插件package.json依赖tmp-promise、unist-util-visit、typescript产物输出到dist/yarn.lock锁定依赖版本。2. 在 Docusaurus 项目中应用修改插件的构建产物为dist/index.jsmain字段指定Docusaurus 通过require(sapling-output-plugin)加载的正是这个产物。因此修改插件源码后需要重新编译再在 Docusaurus 项目内执行yarn install以生效。3. TypeScript 编译开发插件本体时在 website/src/plugins/sapling-output 目录下yarn install yarn build构建站点静态版本前务必执行上述两步。若正在活跃开发插件则改用监听模式yarn install yarn watchTypeScript 监听器会在后台增量更新dist/目录。注意Docusaurus 不会热加载插件产物修改后需要重启 Docusaurus 才能看到变化。4. 调试临时文件插件运行时会在系统临时目录创建前缀为mdx-sapling-output的临时目录默认执行结束后自动删除。如需保留现场用于排查设置环境变量MDX_SAPLING_OUTPUT_DEBUG1 yarn build设置后临时目录将不会被自动清理可以检查生成的example.t包含注入的环境头与补全后的输出来定位问题。六、仓库内的真实使用示例with-output语法已在站点文档中实际投入使用。例如 website/docs/dev/internals/zstdelta.md 中讲解 ZstDelta 的diff/apply用法时就直接书写了只含输入、不含输出的 Python 交互块由插件在构建期补全len(a)、len(diff)、布尔判断等运行结果with-output import bindings, hashlib a b.join(hashlib.sha256(str(i).encode()).digest() for i in range(1000)) len(a) b a[:10000] bx * 10000 a[11000:] diff bindings.zstd.diff(a, b) len(diff) bindings.zstd.apply(a, diff) b 这种“示例即测试、输出即真相”的写作方式保证了文档中的命令输出永远与当前版本的 Sapling 实际行为保持一致也是本插件的核心价值所在。小结sapling-output-plugin通过把 MDX 中的with-output代码块转为.t测试并借助sl debugruntest --fix真实执行实现了文档示例输出的自动化与准确性。它覆盖了从语法设计# hide begin/# hide end、环境注入、输出回填到颜色渲染的完整链路并提供了MDX_SAPLING_OUTPUT_DEBUG、SL等实用的调试与定制手段。若你的文档项目同样基于 Docusaurus并希望命令示例永不过期可直接复用这一插件的实现思路接入方式、源码与命令定义分别见 website/src/plugins/sapling-output/README.md、website/src/plugins/sapling-output/src/index.ts 与 eden/scm/sapling/commands/debug.py。赞分享开发工具CLI后端【免费下载链接】saplingA Scalable, User-Friendly Source Control System.项目地址https://gitcode.com/gh_mirrors/sa/sapling点击查看免费下载相关推荐zsh-completions 补全文档示例代码规范zsh completions 补全文档示例代码规范 zsh completions 是为 ZshZ Shell提供额外补全定义的开源项目旨在通过丰富的开发工具CLISupermemory文档即代码MDX与静态站点生成实践Supermemory文档即代码MDX与静态站点生成实践 痛点与解决方案 你是否正面临这些文档管理难题团队协作时文档版本混乱代码与文档更新不同步静态站点人工智能RAGAgent 记忆AI Agent后端MCP 服务知识图谱前端Kornia Models 文档的「最短可运行示例 真实输出图」页面模式基于 generate_model_examples.py 的自动化文档实践Kornia Models 文档的「最短可运行示例 真实输出图」页面模式基于 generate_model_examples.py 的自动化文档实践 导读计算机视觉人工智能深度学习图像处理上一篇如何免费解锁WeMod Pro高级功能Wand-Enhancer完整使用指南下一篇如何免费解锁Wand专业版一键移除2小时限制的完整教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考