asciidoc最佳实践-maven插件

Nov 10, 2017 • kael


前言

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页面中。