snipgrapher

适用场景

在以下情况下使用此技能：

• 从源代码生成代码片段图片
• 配置可复用的代码片段渲染默认值
• 批量渲染用于文档、社交帖子或更新日志的代码片段素材
• 使用从 npm 发布的 snipgrapher 生成代码片段图片

快速开始

无需配置，即可立即将单个文件渲染为 PNG：

npx snipgrapher render file.ts -o output.png

如需持续使用，请先初始化项目配置，然后再进行渲染：

npx snipgrapher init          # creates snipgrapher.config.json
npx snipgrapher render file.ts --profile default -o output.png

渲染后，请确认输出文件存在且大小不为零，再判定任务成功：

ls -lh output.png   # confirm file exists and size > 0

使用方法

按顺序阅读以下规则文件：

• rules/setup-and-configuration.md - 安装、选择可执行文件、初始化配置并定义配置方案
• rules/rendering-workflows.md - 渲染单个代码片段、批量任务、监视模式和输出实践

核心原则

• 先配置：开始重复渲染前，先创建项目配置
• 确保输出可复现：优先使用命名配置方案和明确的输出路径
• 命令保持可移植：使用适用于已安装二进制文件和 npx 的命令模式
• 便于自动化：有意利用 CLI 标志、配置和环境变量的优先级

常见渲染故障排查

如果渲染失败或输出结果异常，请检查以下常见原因：

• 缺少字体：确保系统已安装配置方案或配置文件中指定的自定义字体
• 不支持的语法：确认 snipgrapher 支持相应语言或扩展名；否则改用纯文本高亮
• 输出为空或已损坏：使用 --verbose（如果支持）重新运行以显示错误详情，并确认输入文件可读且非空
• 未找到配置方案：如果配置文件缺失或格式错误，请运行 npx snipgrapher init 重新生成 snipgrapher.config.json