Skip to content

Latest commit

 

History

History
494 lines (410 loc) · 17.9 KB

README_zh-CN.adoc

File metadata and controls

494 lines (410 loc) · 17.9 KB
Raw

Asciidoctor Maven 插件

Build Status (Travis CI) Coverage Status Maven Central

Asciidoctor Maven 插件是一种官方支持的方式，它可以在 Apache Maven 构建过程中使用 Asciidoctor 转化你的 AsciiDoc 文档。

该文档有如下语言的翻译版：
💡
 本文档是 README 的翻译版。如果发现有什么不一致或者错误的地方，请以原文档为准。

Installation

作为一个典型的 Maven 插件，可以很容易地在 POM 文件的 <plugins> 部分声明使用：

pom.xml 中的插件声明
<plugins>
    <plugin>
        <groupId>org.asciidoctor</groupId>
        <artifactId>asciidoctor-maven-plugin</artifactId>
        <version>1.5.8</version> <!--(1)-->
        ...
    </plugin>
</plugins>

  1. 这个插件的版本紧跟 Asciidoctor 的版本，你可以使用任意喜欢的 Asciidoctor 版本。

使用

执行配置
<plugin>
    ...
    <executions>
        <execution>
            <id>output-html</id>              <!--(1)-->
            <phase>generate-resources</phase> <!--(2)-->
            <goals>
                <goal>process-asciidoc</goal> <!--(3)-->
            </goals>
        </execution>
    </executions>
</plugin>

  1. 这是执行唯一ID。This is simply an unique id for the execution

  2. asciidoctor-maven-plugin 不在任意环节运行，所以必须指定一个环节。

  3. Asciidoctor Maven 插件在此时的执行目标。

配置选项

asciidoctor-maven-plugin 有很多配置选项，这些配置在 Asciidoctor 也是可用的：

sourceDirectory

默认指向 ${basedir}/src/main/asciidoc

sourceDocumentName

an override to process a single source file; 默认指向 ${sourceDirectory} 中的所有文件

sourceDocumentExtensions

（在 v1.5.3 及其以下版本中被命名为 extensions) 一系列需要渲染的不标准的文件扩展名。目前，ad、adoc 和 asciidoc 默认就会被渲染。

outputDirectory

默认指向 ${project.build.directory}/generated-docs

baseDir

（不是 Maven 的 basedir）设置资源（例如被包含的文件）的根目录，默认指向 ${sourceDirectory}。

skip

跳过生成则设置为 true， 默认`false`。

preserveDirectories

指明是否渲染成和源文件相同的目录结构。默认为 false。 当为 true 时，不在将所有文件都生成到同一个目录中，而是将输出文件生成到相同的目录结构中。看下面的例子。

    ├── docs                          ├── docs
    │   ├── examples.adoc             │   ├── examples.html
    │   └── examples            =>    │   └── examples
    │       ├── html.adoc             │       ├── html.html
    │       └── docbook.adoc          │       └── docbook.html
    └── index.adoc                    └── index.html
relativeBaseDir

只有在 baseDir 没有指明的情况下才使用。启用则指明每一个 AsciiDoc 文件都必须从同一个目录下搜索它的资源文件（例如被包含的文件）。在内部，对于每一个 AsciiDoc 源文件，设置 baseDir 与源文件相同的路径。默认为 false。

imagesDir

默认指向 images，它是相对于源码目录的相对路径。

backend

默认是 docbook。

doctype

默认为 null （它将触发 Asciidoctor 的默认值 article）

eruby

默认为 erb，被 JRuby 使用

headerFooter

默认为 true

templateDir

默认不可用，默认值为 null

templateEngine

默认不可用

sourceHighlighter

启用语法高亮，设置语法高亮器（当前仅支持 coderay 和 highlight.js）

attributes

包含传递给 Asciidoctor 的属性的 Map<String,Object>，默认为 null

embedAssets

内嵌的 CSS 文件，指向输出，默认为 false

gemPaths

用于指明一个或多个 gem 安装路径（等同 GEM_PATH 环境变量），默认为 empty

requires

a List<String> to specify additional Ruby libraries not packaged in AsciidoctorJ, empty by default

extensions

被包含进转化过程的扩展列表（可从 AsciidoctorJ’s Extension API 更多可选项的信息）。对于每一个扩展，实现类必须在 className 参数中指明，blockName 参数只有在配置 BlockProcessor， BlockMacroProcessor 或 InlineMacroProcessor 才需要指定。下面是一个配置例子：

<plugin>
    ...
    <executions>
        <execution>
            <configuration>
                ...
                <extensions>
                    <extension>
                        <className>org.asciidoctor.maven.SomePreprocessor</className>
                    </extension>
                    <extension>
                        <className>org.asciidoctor.maven.SomeBlockProcessor</className>
                        <blockName>yell</blockName>
                    </extension>
                </extensions>
            </configuration>
        </execution>
    </executions>
    <dependencies>
        <dependency> <!--(1)-->
            <groupId>org.asciidoctor.maven</groupId>
            <artifactId>my-asciidoctor-extensions</artifactId>
            <version>1.0.0</version>
        </dependency>
    </dependencies>
</plugin>

  1. 注意：处理器必须被包含在插件的执行类路径中，而不是项目的。

📎
 扩展也可以通过 SPI 接口实现整合进来。这种方法就不需要在 pom.xml 中作任何配置，查看 Extension SPI 获得更多细节。

内置属性

Asciidoctor 包含了一系列属性。下面是它们的一个列表以及它们的作用。

title

一个文档的概要标题。

📎
 为了向后兼容性，这个属性还可以在顶级配置项中使用。

很多其他属性可用。在 Asciidoctor 给出一个权威列表之前，你可以在 属性列表 中看到更多帮助。

为了利用 Asciidoctor 的其他选项和属性，将来会有更多属性被添加进来。 属性部分的任何设置如果和命名属性配置相冲突，将会被命名属性配置所覆盖。 这些设置都可以在插件部分的 <configuration> 部分中改变：

插件配置选项
<plugin>
    <configuration>
        <sourceDirectory>src/docs/asciidoc</sourceDirectory>
        <outputDirectory>target/docs/asciidoc</outputDirectory>
        <backend>html</backend>
        <doctype>book</doctype>
        <attributes>
            <stylesheet>my-theme.css</stylesheet>
        </attributes>
    </configuration>
</plugin>

传递 POM 属性

可以将在 POM 中定义的属性传递给 Asciidoctor 处理器。下面的例子演示在生成文档中包含 POM artifact 版本号。

这些要在 configuration 部分的 attributes 小节中，通过创建自定义 AsciiDoc 属性来完成。 AsciiDoc 属性值使用常用的 Maven 方式来定义： ${myMavenProperty}。

<attributes>
    <project-version>${project.version}</project-version>
</attributes>

这个自定义的 AsciiDoc 属性接下来就可以在文档中像如下方式使用：

The latest version of the project is {project-version}.
💡

如果你想使用项目的版本作为文档的修订版，使用如下结构：

:revnumber: {project-version}

这样，版本号将会出现在输出文档的头部和尾部。

设置布尔值

sciidoctor 中的布尔属性，例如 sectnums， linkcss 或 copycss 可以使用 true 值来设置，也可以使用 false 来取消设置。

示例

在 Asciidoctor Maven 插件配置的 <attributes> 部分：

<sectnums>true</sectnums>
<linkcss>false</linkcss>

在 Asciidoctor Maven 示例 项目中，你可以发现更多信息以及可以直接复制粘贴的示例。

命令行配置

配置选项可以直接在命令行中使用系统属性来设置（但不可删除），如下：

mvn generate-resources -Dasciidoctor.sourceDirectory=src/docs -Dasciidoctor.outputDirectory=target/docs

所有选项按照这样的命名规范： `asciidoctor.` + option_name。

为了属性配置有更高的灵活性，请遵循不同的行为。 通过命令行定义的属性将会追加到在 XML 中配置的属性列表上。 这样导致的结果就是如果这些属性添加命令行中，这些属性或者其他配置选项会被更新。 例如，下面的这个配置将会被后面的命令行选项修改掉。

<configuration>
    <backend>html5</backend>
    <sourceHighlighter>coderay</sourceHighlighter>
    <attributes>
        <toc>left</toc>
    </attributes>
</configuration>
mvn generate-resources -Dasciidoctor.attributes=toc=right
mvn generate-resources -Dasciidoctor.attributes="toc=right source-highlighter=highlight.js imagesdir=my_images"

注意在第二种情况，你需要引号把属性设置括起来，其中，source-highlighter 是 asciidoctor 的属性值名，用于更新配置。

相同文件的多个输出

Maven 可以多次执行 Mojo。 为了避免重新发明类似 Mojo 的轮子，我们将会由 Maven 来处理多次执行。 搭建的例子如下：

多个配置输出
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.8</version>
    <executions>
        <execution>
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <sourceHighlighter>coderay</sourceHighlighter>
                <backend>html</backend>
                <attributes>
                    <toc/>
                    <linkcss>false</linkcss>
                </attributes>
            </configuration>
        </execution>
        <execution>
            <id>output-docbook</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>docbook</backend>
                <doctype>book</doctype>
            </configuration>
        </execution>
    </executions>
    <configuration>
        <sourceDirectory>src/main/asciidoc</sourceDirectory>
        <headerFooter>true</headerFooter>
        <imagesDir>../resources/images</imagesDir> <!--(1)-->
    </configuration>
</plugin>

  1. imagesDir 应该是源文件的相对路径。它默认指向 images，但是在这里示例中，用于文档的图片还可以用于项目中的任何地方。

在 executions 外定义的任何配置都会被每一个执行过程所继承。 这展示了定义公用选项的最简单方式。

Maven 站点集成

为了使用 AsciiDoc 创建你的 Maven 生成的站点，你必须添加一个关于 Asciidoctor 插件的依赖到 maven-site-plugin 声明中。

Maven 站点集成
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <version>3.4</version>
            <dependencies>
                <dependency>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-maven-plugin</artifactId>
                    <version>1.5.8</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

所有基于 AsciiDoc 的文件都应该放在 src/site/asciidoc`中，并且扩展名为 `.adoc。 这些文件都会被渲染到 target/site 目录中。 例如，src/site/asciidoc/usage.adoc 文件将会被渲染到 target/site/usage.html。

Asciidoctor 基础目录默认配置为 src/site/asciidoc，这可以被覆盖。 同样需要注意 AsciiDoc 文件可以转化成嵌入 HTML 并被插入到网站的页面布局中。 这样，某些特性，例如边框目录，将不可用。

确保你添加了 menu 元素为每一个页面，这样你就可以从网站导航栏来访问它：

<body>
    ...
    <menu name="User guide">
        <item href="usage.html" name="Usage" />
    </menu>
    ...
</body>

配置

从 插件的 1.5.3 版，你可以在插件声明中通过特殊的配置文件来配置 Asciidoctor，就像插件的主要目录。 虽然，这里有一个非常重要的不同。 在站点集成的所有 Asciidoctor 配置必须嵌入到 <asciidoc> 元素中。 至从 <configuration> 元素比 Asciidoctor 集成更多地用于配置，这就成为必须的。

这有一个例子来展示如果设置这些选项、属性以及忽略局部 AsciiDoc 文件（比如以下划线开头的文件）。

使用 Asciidoctor 来配置 Maven 站点集成
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-site-plugin</artifactId>
    <version>3.4</version>
    <configuration>
        <asciidoc>
            <templateDirs>
                <dir>src/site/asciidoc/templates</dir>
            </templateDirs>
            <requires>
                <require>asciidoctor-diagram</require>
            </requires>
            <attributes>
                <source-highlighter>coderay</source-highlighter>
                <coderay-css>style</coderay-css>
            </attributes>
        </asciidoc>
        <moduleExcludes>
            <asciidoc>**/_*.adoc</asciidoc>
        </moduleExcludes>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>1.5.3</version>
        </dependency>
    </dependencies>
</plugin>
❗
 Asciidoctor 基本目录（比如文档根目录）默认配置为 src/site/asciidoc，它可以被 baseDir 选项覆盖。

你将会注意到某些 AsciiDoc 文件被排除在外。 这可以防止站点集成将局部文件（例如被包含文件）处理成独立文件。 你可以根据自己的喜欢来设置这个模式。 现在还没有方式来自动配置这个。

你可以通过指定模板目录来激活内置的模板转化器（例如： templatesDir）。 这个特性可以让你提供自定义的目标来转化文档树的任意节点（例如文档、章节、列表等等）。 当努力定制网站外观时，自定义目标就显得特别有帮助了。

黑客

开发者想搭建起来黑客这个项目也不难。要求很简单：

  • Java

  • Maven 3

其他的将会被 Maven 自动下载下来。这是一个典型的 Maven Java 项目，没有什么特别。你可以使用 IntelliJ、Eclipse 或 Netbeans 来开发项目，不需求起奇技淫巧。

构建

标准 Maven 构建：

mvn clean install

测试

Spock 被用于测试 Mojo 调用。它会被 Maven 自动下载。运行测试非常简单，如下：

mvn clean test

或通过其他目标来运行测试。

📎
 如果我能选择到好多方法来搭建 Ruby 测试环境，我也会这样做。但是，现在没有。

提示和技巧

为每个版本在不同目录中生成文档

<configuration>
    ...
    <outputDirectory>target/generated-docs/${project.version}</outputDirectory>
    ...
</configuration>

启用章节数值

<configuration>
    ...
    <attributes>
        ...
        <sectnums>true</sectnums>
        ...
    </attributes>
    ...
</configuration>