本文介绍如何解决基于 api blueprint 的 markdown 文件生成空 html 文件的问题，推荐采用更稳定、开箱即用的 aglio 工具替代手动配置 go 构建链，实现一键式 html 渲染。
本文介绍如何解决基于 api blueprint 的 markdown 文件生成空 html 文件的问题，推荐采用更稳定、开箱即用的 aglio 工具替代手动配置 go 构建链，实现一键式 html 渲染。
在 API 设计与文档协作中，API Blueprint 是一种广泛使用的、以 Markdown 语法编写的 API 描述规范。然而，许多开发者在尝试通过原始 Go 工具链（如 snowcrash + 自定义 generator）将 .md 或 .apib 文件渲染为 HTML 时，常遇到输出文件为空（test.html 生成但内容为空）的问题。根本原因在于：该旧式 Go 工具链依赖多个已弃用或难以兼容的第三方包（如 bitbucket.org/pkg/inflect）、构建路径敏感（需严格 symlink 到 $GOPATH/src）、模板解析逻辑脆弱，且缺乏对现代 API Blueprint v1A 规范的完整支持。
相比之下，Aglio 是目前最成熟、维护活跃的 API Blueprint 渲染器，基于 Node.js 实现，内置完整解析器（使用 Drafter）、响应式 HTML 模板、实时预览及扩展能力，无需手动管理 Go 环境或模板路径。
✅ 推荐解决方案（三步完成）：
-
全局安装 Aglio（确保已安装 Node.js ≥ 14）：
立即学习“前端免费学习笔记（深入）”；
npm install -g aglio
-
验证文件格式：确保你的源文件是标准 API Blueprint 格式（后缀建议 .apib，而非 .md），开头必须包含 FORMAT: 1A 声明，例如：
FORMAT: 1A
My API
GET /users
- Response 200 (application/json)
- Body [{"id": 1, "name": "Alice"}]
-
执行渲染：
aglio -i api.apib -o output.html
生成的 output.html 即为交互式、带搜索、侧边导航和代码高亮的完整 API 文档。
⚠️ 注意事项：
- 不要混用 .md 和 .apib 扩展名：Aglio 默认按 .apib 解析；若坚持用 .md，需显式指定 --format apib；
- 模板自定义？Aglio 支持 -t 参数加载自定义主题（如 aglio -i api.apib -t flatly -o out.html），也支持导出为 PDF（需额外安装 PhantomJS 或使用 aglio --export-pdf）；
- 若遇 Error: Parse error，请检查 FORMAT: 1A 是否缺失、缩进是否统一（API Blueprint 对空格敏感），可使用 Apiary Parser Playground 在线校验。
总结：放弃复杂易错的 Go 手动构建流程，拥抱 Aglio——它不仅彻底规避了空文件问题，还提供生产就绪的文档体验、CI/CD 友好性（单命令集成）和持续更新的规范兼容性。对于新项目，Aglio 应作为 API Blueprint 渲染的事实标准工具。
