Asciidoctor入门工具包

您刚刚发现了Asciidoctor，并且您想知道如何快速有效地开始使用AsciiDoc文档？下面是生成和查看与AsciiDoc内容相关联的HTML代码的可能方式列表。

Table des matières

DocGist : 在线编辑器
浏览器扩展程序
现代文本编辑器
安装Asciidoctor
- 从珠宝开始
- 从一个容器开始
构建环境

DocGist : 在线编辑器

'''DocGist 是一个在线的 AsciiDoc 编辑器，它可以让你在编辑文档的同时提供实时的 HTML 渲染，与其他用户分享你的文档，并且多人可以在同一个文档上协作。这个工具不需要任何特别的安装，也不需要创建账户。'''

它可以通过 http://gist.asciidoctor.org 地址访问。

浏览器扩展程序

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

Chrome 扩展程序

Chrome扩展https://chrome.google.com/webstore/detail/asciidoctorjs-live-previe/iaalpfgpbocpdfblpnhhgllgbdbchmia[Asciidoctor.js Live Preview]也允许您选择预定义的主题或导入您自己的自定义主题(CSS)。

从Chrome网上应用店安装扩展

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

附加组件 Firefox

火狐浏览器的插件https://addons.mozilla.org/fr/firefox/addon/asciidoctorjs-live-preview[Asciidoctor.js Live Preview]像其他扩展一样提供了实时HTML预览功能。

从Firefox管理器安装插件（版本0.5.1）
通过下载https://github.com/asciidoctor/asciidoctor-firefox-addon/releases/download/v0.5.3/asciidoctor-firefox-addon-0.5.3-signed.xpi[asciidoctor-firefox-addon.xpi文件（版本0.5.4）]来安装最新发布的版本。

Tip	为了使用插件的最新版本，最好通过从GitHub下载最新的发行版来安装。

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

插件 Opera

Chrome扩展与Opera兼容，因此这个插件与Chrome的是一样的，它提供了相同的功能。

从Opera管理器[安装插件]。

关于GitHub项目的更多信息可以在https://github.com/asciidoctor/asciidoctor-chrome-extension[asciidoctor-chrome-extension]找到。（是的，这个插件和Chrome的是一样的）。

现代文本编辑器

Asciidoctor 存在于大多数现代文本编辑器中，也有一个专门的编辑器是为它设计的。

AsciidocFX

AsciidocFX是一款基于Asciidoctor的编辑器，它提供了非常丰富的功能：支持多平台（Windows、Mac、Linux）、PDF、HTML、MOBI、EPUB等多种格式导出。

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

Atom的软件包

Asciidoctor 社区为 Atom 提供了两个补充包装。

AsciiDoc 预览包: 这个包激活了对应于输入AsciiDoc的HTML的实时可视化。它还为Asciidoctor的变量提供了自动完成功能。
AsciiDoc package: 这个包激活了对AsciiDoc语言的支持，包括语法高亮显示。

Brackets的扩展

Adobe的Brackets编辑器的扩展http://brackets.dnbard.com/extension/nerk.asciidoc-preview[AsciiDoc Preview]除了提供实时HTML预览之外，还提供了一些有趣的功能，比如能够同步当前AsciiDoc源码的位置与相应的HTML节。这个扩展还支持数学表达式以及PlantUml、Ditaa和Graphviz图表。

更多信息：

扩展 AsciiDoc 预览插件针对 Brackets
GitHub项目 brackets-asciidoc-preview

IntelliJ

对于Java开发者来说，IntelliJ插件（IDEA及其系列产品）为AsciiDoc提供了支持，使得他们可以在同一环境下编写代码和相关文档。

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

安装Asciidoctor

从珠宝开始

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

您可以在 RubyGem 找到所有的宝石（官方的或非官方的）。

从一个容器开始

$ docker pull asciidoctor/docker-asciidoctor // (1)
$ docker run -v $(pwd)):/documents/ asciidoctor/docker-asciidoctor asciidoctor -D /documents *.adoc // (2)

从DockerHub下载https://hub.docker.com/r/asciidoctor/docker-asciidoctor/[官方Asciidoctor Docker镜像]到本地。
在容器中使用Asciidoctor的示例。

关于GitHub项目docker-asciidoctor的更多信息，请访问https://github.com/asciidoctor/docker-asciidoctor[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>

插件版本接近主要的Ruby宝石版本。

有关使用项目 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 中找到。

蚂蚁任务

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>

“lib” 是包含 JAR 文件 asciidoctor-ant.jar 的目录。

有关使用Ant配置项目的更多信息，请访问 asciidoctor-ant。