开始使用 Asciidoctor 的工具

作者 Guillaume Scheibel and Maxime Gréau -

您刚刚发现了 Asciidoctor，并想知道从哪里开始才能高效地使用您的 AsciiDoc 文档？以下是生成与 AsciiDoc 内容相关的 HTML 代码的各种可能性。

DocGist：在线编辑器

DocGist 是一个 AsciiDoc 的在线编辑器，它允许您实时编辑文档并生成 HTML 预览，与其他用户共享您的文档，以及多人协作编辑同一份文档。此工具无需任何特定安装或账户创建。

它可以在 http://gist.asciidoctor.org 访问。

DocGist

浏览器扩展

通过简单的浏览器扩展，可以实时查看本地或远程 AsciiDoc 源码文件的 HTML 渲染。

Chrome 扩展

Chrome 的 Asciidoctor.js Live Preview 扩展还允许您选择预定义的主题或导入自己的自定义主题 (CSS)。

更多信息请参考 GitHub 项目 asciidoctor-chrome-extension。

Chrome Asciidoctor.js Live Preview

Firefox 插件

Firefox 的 Asciidoctor.js Live Preview 插件与其它扩展一样，提供实时 HTML 可视化。

要使用最新版本的插件，最好通过从 GitHub 下载最新发布版本来安装。

更多信息请参考 GitHub 项目 asciidoctor-firefox-addon。

Firefox Asciidoctor.js Live Preview

Opera 插件

由于 Chrome 扩展与 Opera 兼容，这个插件与 Chrome 的相同，因此提供相同的功能。

更多信息请参考 GitHub 项目 asciidoctor-chrome-extension。(是的，这个插件与 Chrome 的相同。)

Opera Asciidoctor.js Live Preview

现代文本编辑器

Asciidoctor 在大多数现代文本编辑器中都有体现，并且还有一个专门为其设计的编辑器。

AsciidocFX

AsciidocFX 是一个基于 Asciidoctor 的编辑器，提供了大量功能：跨平台（Windows、Mac、Linux），导出为 PDF、HTML、MOBI、EPUB 等。

项目的完整文档可在 http://asciidocfx.com/ 网站上找到。

AsciidocFX Editeur

Atom 包

Asciidoctor 社区提供了 2 个附加的 Atom 包：

AsciiDoc Preview 包

此包可激活对输入 AsciiDoc 的相应 HTML 的实时预览。它还提供 Asciidoctor 变量的自动完成功能。

AsciiDoc 包

此包启用 AsciiDoc 语言支持，特别是语法高亮。

Atom Editeur

Brackets 扩展

Adobe Brackets 编辑器的 AsciiDoc Preview 扩展除了实时 HTML 预览外，还提供了有趣的功能，例如将当前位置在 AsciiDoc 源文件中的位置与相应的 HTML 部分同步。此扩展支持数学表达式以及 PlantUml、Ditaa 和 Graphviz 图表。

更多信息

asciidoctor bracket extension demo

IntelliJ

对于 Java 开发者来说，IntelliJ (IDEA 及系列) 的 AsciiDoc 插件允许他们在同一个环境中编写代码和相关的文档。

更多信息请参考 GitHub 项目 asciidoctor-intellij-plugin。

asciidoctor intellij plugin demo

安装 Asciidoctor

从 gem 开始

$ gem install asciidoctor
$ gem install asciidoctor-diagram
$ gem install asciidoctor-pdf --pre
$ gem install asciidoctor-epub3 --pre

您可以在 RubyGem 上找到所有 gem（官方或非官方）。

从容器开始

$ docker pull asciidoctor/docker-asciidoctor (1)
$ docker run -v $(pwd)):/documents/ asciidoctor/docker-asciidoctor asciidoctor -D /documents *.adoc (2)
1 从 官方 Asciidoctor Docker 镜像 的 DockerHub 下载到本地。
2 在容器中使用 Asciidoctor 的示例。

更多关于 GitHub 项目 docker-asciidoctor 的信息。

构建环境

为了从持续集成系统生成文档，例如，Asciidoctor 为 Java 环境中的构建工具提供了插件。

Maven 插件

pom.xml
<plugins>
    <plugin>
        <groupId>org.asciidoctor</groupId>
        <artifactId>asciidoctor-maven-plugin</artifactId>
        <version>1.5.3</version> (1)
        ...
    </plugin>
</plugins>
1 插件版本与主要的 Ruby gem 版本相近。

更多关于使用 asciidoctor-maven-plugin 项目进行 Maven 配置的信息。

根据用例的配置示例可在 asciidoctor-maven-examples 项目中找到。

Gradle 插件

build.gradle
buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.3'
    }
}

apply plugin: 'org.asciidoctor.convert'

更多关于使用 asciidoctor-gradle-plugin 项目进行 Gradle 配置的信息。

根据用例的配置示例可在 asciidoctor-gradle-examples 项目中找到。

Ant 任务

build.xml
<project xmlns:asciidoctor="antlib:org.asciidoctor.ant">
...
    <target name="doc">
        <taskdef uri="antlib:org.asciidoctor.ant" resource="org/asciidoctor/ant/antlib.xml" classpath="lib/asciidoctor-ant.jar"/> (1)
        <asciidoctor:convert sourceDirectory="src/asciidoc" outputDirectory="target"/>
    </target>
...
</project>
1 “lib” 是包含 asciidoctor-ant.jar 的目录。

更多关于使用 asciidoctor-ant 项目进行 Ant 配置的信息。

  • 1 / 1