asciidoc最佳实践-maven插件

前言
目录结构
pom.xml配置
编写建议
预览
标题建议

前言

AsciiDoc是一种轻量型的标记语言，语法简单易用，兼容Markdown的同时，提供了更丰富的标记功能，非常适用于写电子文档，使用AsciiDoc 的时候，为了编写和维护方便，经常需要按照一定的规范组织目录结构，而发布的目录结构不一定和编写过程一致，因此本文主要是讨论我自己在尝试使用AsciiDoc编写文档时的最佳实践。

目前只讨论使用maven插件搭建目录结构和发布的方式。

目录结构

- root
    -src
        - main
            - asciidoc
                - ask
                    ask.adoc
                - index.adoc
            - resources
                - images
                    - ask
                        - ask_1.png
    - target
        - book
    - pom.xml

根目录是root;
使用src/main/asciidoc作为源码目录，即asciidoctor-maven-plugin插件的默认源码目录;
将所有的资源文件放到src/main/resources目录下，如：图片的目录在src/main/resources/images目录下;
target目录是默认输出目录，并配置将asciidoc编译的结果输出到target/book目录下;

pom.xml配置

如下配置即可完全按照上面的目录结构生成最终的电子书。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>kael.demo</groupId>
    <artifactId>asciidoc</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <maven.compiler.encoding>UTF-8</maven.compiler.encoding>
        
        <asciidoctorj.version>1.5.6</asciidoctorj.version>
        <asciidoctorj.diagram.version>1.5.4.1</asciidoctorj.diagram.version>
        <jruby.version>1.7.26</jruby.version>
    </properties>
    <build>
        <!-- 默认命令，配置后可以直接使用mvn编译 -->
        <defaultGoal>process-resources</defaultGoal>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <targetPath>${project.build.directory}/book</targetPath>
            </resource>
        </resources>
        <plugins>
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.5</version>
                <executions>
                    <execution>
                        <id>output-html</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                    </execution>
                </executions>
                <dependencies>
                    <!-- Comment this section to use the default jruby artifact provided by the plugin -->
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>${jruby.version}</version>
                    </dependency>
                    <!-- Comment this section to use the default AsciidoctorJ artifact provided by the plugin -->
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj</artifactId>
                        <version>${asciidoctorj.version}</version>
                    </dependency>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-diagram</artifactId>
                        <version>${asciidoctorj.diagram.version}</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <outputDirectory>${project.build.directory}/book</outputDirectory>
                    <sourceDocumentName>index.adoc</sourceDocumentName>
                    <sourceHighlighter>prettify</sourceHighlighter>
                    <backend>html</backend>
                    <preserveDirectories>false</preserveDirectories>
                    <requires>
                        <require>asciidoctor-diagram</require>
                    </requires>
                    <attributes>
                        <toc>left</toc>
                        <icons>font</icons>
                        <sectanchors>true</sectanchors>
                        <!-- set the idprefix to blank -->
                        <idprefix/>
                    </attributes>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

编写建议

编写AsciiDoc文本推荐使用idea/WebStorm，安装AsciiDoc插件即可实施预览：

在编写时，所有的源码文档使用.adoc作为扩展名。

在文档中引用图片时，遵循如下规范：

在个源码文件的顶部定义图片根目录相对当前目录的相对路径
每个目录的图片在图片根目录下创建一个同名目录
每个源码文件引用的图片命名按照{源码文件名}_{序号递增}.png

如上面提到的目录结构，在src/main/asciidoc/index.adoc顶部定义图片根目录：

ifndef::imagesdir[:imagesdir: ../resources/images]

在src/main/asciidoc/ask/index.adoc顶部定义图片根目录：

ifndef::imagesdir[:imagesdir: ../../resources/images]

那么在引用图片的时候，可以按照如下方式：

image::ask/ask_1.png

在src/main/asciidoc/index.adoc中尽量不直接写内容，使用include指令组合各个章节即可。这样定义的好处有几点：

无论是AsciiDoc的预览工具，还是最终编译发布的电子书，都可以完美看到图片，不会出现为了保证发布时图片不缺失，而放弃预览时看到图片的情况。

各个目录的图片文件路径清晰，一旦需要做比较大的调整的时候，可以准确的找到所有文件对应的图片路径

预览

编写的过程，经常需要预览整个文档，这种情况推荐使用一个简单的静态http服务器，如http-server。

指定监听target/book目录即可，

$> http-server target/book -p 4001 -e html

每次修改完需要查看的时候，只需要使用mvn clean process-resources编译一次，就可以直接在浏览器预览整体效果了。

标题建议

asciidoc有很多属性可以设置，一般建议的电子书中声明如下属性：

电子书标题
==========
卡尔 <kael.peng@gmail.com>
v2, 2017-11-02
:source-highlighter: prettify
:data-uri:

这里source-highlighter是语法高亮，data-uri是将图片内嵌到html页面中。