Asciidoctor
用 Ruby 写的 AsciiDoc 文本处理器,默认输出 HTML5、DocBook 5 和 man page,适合技术文档作者把接近纯文本的稿子直接发布成网页或手册。
4 次可以打开平均 2.6 秒11 月 22 日 起国内不可直接访问
本站从国内机房定期实测。竖条由远及近:绿 = 可以打开,橙 = 国内不可直接访问,灰 = 打不开。Asciidoctor 是一个用 Ruby 写的文本处理器,专门解析 AsciiDoc 格式的文档,再把它转换成可以直接发布的格式。AsciiDoc 本身是一种轻量级标记语言,写法接近纯文本,但能表达标题、列表、代码块、表格、交叉引用等结构。Asciidoctor 负责读取这些源文件,输出成 HTML5、DocBook 5 或 man page(手册页),PDF 和 EPUB 3 则由另外安装的扩展包提供。
主要功能
默认自带三种输出格式的转换器:HTML5、DocBook 5 和 man page。HTML 输出附带一套默认样式表,并集成了 Font Awesome 图标、highlight.js、Rouge、Pygments 的代码高亮,以及 MathJax 处理数学公式,打开就能看到成型的页面。除了命令行调用,也可以通过 API 在程序里处理 AsciiDoc,或者用 AsciidoctorJ 在 JVM 上运行、用 Asciidoctor.js 在 JavaScript 环境(包括浏览器)里运行。
围绕核心处理器还有一批扩展和工具:Asciidoctor Diagram 用来画图,Maven 和 Gradle 插件接入构建流程,reveal.js 转换器做幻灯片,EPUB 3 转换器出电子书,IntelliJ 插件和浏览器扩展提供写作与预览环境。
安装与平台
Asciidoctor 以 RubyGem 的形式发布在 RubyGems.org 上,包名是 asciidoctor,可以用 gem 或 bundle 安装。它也提供 Docker 镜像,以及多个 Linux 发行版的软件包(Alpine、Arch、Debian、Fedora、OpenSUSE、Ubuntu),macOS 上可以通过 Homebrew 或 MacPorts 安装。运行需要 Ruby 环境,支持 CRuby 2.3 到 3.3、JRuby 9.1 到 9.4 以及 TruffleRuby。在非英文的 Windows 环境里调用时可能遇到编码错误,官方建议把 RUBYOPT 设为 utf-8 来避免。
适合谁
写技术文档、需要把同一份源文件输出成网页、手册和电子书的人,用 Asciidoctor 可以省去手工排版。它也是 AsciiDoc.py 的后继项目,原来用 AsciiDoc.py 的用户可以按迁移指南换过来。项目开源,代码托管在 GitHub 上,文档集中在 docs.asciidoctor.org。
