asciidoctor/asciidoctor.js

说明与用途

**项目简介（2‑3 句）**
asciidoctor/asciidoctor.js 是 Asciidoctor（现代 AsciiDoc 解析与渲染引擎）的 JavaScript 移植版，能够在浏览器或 Node.js 环境中直接将 AsciiDoc 文本转换为 HTML、PDF 等格式。它保留了原生 Asciidoctor 的语法特性和扩展能力，同时提供了 npm 包的便捷分发方式。

---

价值点

1. **统一前后端渲染**：无需在后端使用 Ruby 或 Java 版 Asciidoctor，前端即可完成文档渲染，适合单页应用、文档编辑器或静态站点生成器。
2. **生态兼容**：遵循 Asciidoctor 语法标准，已有的 AsciiDoc 文档、宏和扩展可以直接迁移，降低学习成本。

3 **轻量可嵌入**：作为 npm 包发布，依赖仅限 JavaScript，易于在现有 Node.js 项目或前端构建链中引入。

---

典型接入方式

| 场景 | 步骤 | 示例代码 |
|------|------|----------|
| **Node.js 脚本或构建工具** | 1. npm i asciidoctor.js <br>2. 在代码中 require 或 import <br>3. 调用 asciidoctor() 进行转换 | ``js\nconst asciidoctor = require('asciidoctor.js')();\nconst html = asciidoctor.convert('= Title\\n\\nHello *AsciiDoc*');\nconsole.log(html);\n`` |
| **浏览器实时预览** | 1. 通过 <script type="module"> 引入 CDN（如 jsDelivr）或本地打包的文件 <br>2. 调用全局 asciidoctor() <br>3. 将返回的 HTML 插入页面 | ``html\n<script type="module">\nimport asciidoctor from 'https://cdn.jsdelivr.net/npm/asciidoctor.js/dist/browser/asciidoctor.min.js';\nconst ad = asciidoctor();\nconst html = ad.convert('# Demo');\ndocument.getElementById('preview').innerHTML = html;\n</script>\n<div id="preview"></div>\n`` |
| **与静态站点生成器（如 Eleventy、Gatsby）结合** | 在生成器的插件或自定义过滤器里调用 asciidoctor.convert，把 .adoc 文件转为 HTML 再交给生成器渲染 | ``js\n// Eleventy filter example\nmodule.exports = function(eleventyConfig) {\n const asciidoctor = require('asciidoctor.js')();\n eleventyConfig.addFilter('adoc', content => asciidoctor.convert(content));\n};\n`` |

> **小技巧**：如果项目需要 PDF 输出，可配合 asciidoctor-pdf（Ruby）或使用 asciidoctor.js 生成 HTML 后交由 puppeteer/playwright 打印为 PDF。

---

生产可用性评估

| 维度 | 现状 | 结论 |
|------|------|------|
| **活跃度** | 最近一次提交：2026‑06‑24，拥有 797 ★、153 Fork，社区仍在维护。 | ✅ 可接受 |
| **成熟度** | 已经是 Asciidoctor 官方的 JavaScript 移植版，功能基本覆盖 Asciidoctor 2.x 的核心特性。 | ✅ 稳定 |
| **依赖风险** | 仅依赖 Node.js 标准库和少量轻量 polyfill，未引入大型二进制依赖。 | ✅ 低风险 |
| **文档与示例** | README 提供基本用法，GitHub Wiki 与社区博客有不少集成案例。 | ✅ 足够 |
| **生产建议** | - 在正式环境前先做 **小规模 PoC**（如单文件渲染或编辑器插件）<br>- 通过 CI 检查 asciidoctor.js 版本升级的兼容性<br>- 若需要 PDF，考虑额外的渲染链路或使用服务器端 Asciidoctor 进行二次处理 | ⚙️ 可在内部系统或面向用户的文档平台投入使用，前提做好版本锁定和回归测试。 |

**总体判断**：asciidoctor.js 具备中等到高的生产可用性，适合作为原型、内部工具或面向终端用户的文档编辑/渲染服务的核心组件。只要在上线前完成依赖锁定、兼容性回归以及性能基准（尤其是大文档渲染时），即可安全投入生产。

实际用途

asciidoctor/asciidoctor.js may be useful when its README and activity match a concrete workflow.

限制与审查说明

Medium: useful for prototypes or internal workflows, with dependency and maintenance checks before production.