search

asciidoctor / asciidoctor-ant

:ant: Ant task to render Asciidoc documentation
Apache License 2.0
9 stars 5 forks source link

readme

= asciidoctor-ant Task

:asciidoc-url: http://asciidoc.org :asciidoctor-url: http://asciidoctor.org :asciidoctorj-url: https://github.com/asciidoctor/asciidoctorj :asciidoctor-maven-url: https://github.com/asciidoctor/asciidoctor-maven-plugin :issues: https://github.com/asciidoctor/asciidoctor-ant/issues :ant-url: http://ant.apache.org/ :asciidoctor-ant-maven-repo: http://repo1.maven.org/maven2/org/asciidoctor/asciidoctor-ant/

image:https://travis-ci.org/asciidoctor/asciidoctor-ant.svg?branch=master["Build Status", link="https://travis-ci.org/asciidoctor/asciidoctor-ant"]

The asciidoctor-ant is the official means of using {asciidoctor-url}[Asciidoctor] to render all your {asciidoc-url}[AsciiDoc] documentation using {ant-url}[Apache Ant].

== Installation

=== Prerequesites

=== Download

You can download the uber jar of asciidoctor-ant in {asciidoctor-ant-maven-repo}[Maven Central]. This jar contains the Ant task and its dependencies : JRuby and {asciidoctorj-url}[asciidoctorj].

[source,xml] .Using Ant

... <get src="http://repo1.maven.org/maven2/org/asciidoctor/asciidoctor-ant/${asciidoctor-version}/asciidoctor-ant-${asciidoctor-version}.jar" dest="lib/asciidoctor-ant.jar" usetimestamp="true"/> ...

NOTE: you can also download a core artifact without the asciidoctorj dependencies (available since 1.5.4).

=== Usage

[source,xml]

... <1> ...
<1> "lib" is a directory containing the uber jar asciidoctor-ant.jar === Configuration options There are several configuration options that the asciidoctor-ant Task uses. The options are similar to {asciidoctor-maven-url}[asciidoctor-maven-plugin] : sourceDirectory:: the source directory of Asciidoc files (mandatory) sourceDocumentName:: an override to process a single source file; defaults to all files in `${sourceDirectory}` outputDirectory:: the ouput directory (mandatory) baseDir:: (not ant's basedir) enables to set the root path for resouces (e.g. included files), defaults to Ant project base directory preserveDirectories:: enables to specify whether the documents should be rendered in the same folder structure as in the source directory or not, defaults to `false`. When `true`, instead of generating all output in a single folder, output files are generated in the same structure. See the following example [source] ---- ├── docs ├── docs │ ├── examples.adoc │ ├── examples.html │ └── examples => │ └── examples │ ├── html.adoc │ ├── html.html │ └── docbook.adoc │ └── docbook.html └── index.adoc └── index.html ---- relativeBaseDir:: only used when baseDir is not set, enables to specify that each AsciiDoc file must search for its resources in the same folder (for example, included files). Internally, for each AsciiDoc source, sets `baseDir` to the same path as the source file. Defaults to `false` imagesDir:: defaults to `images`, which will be relative to the directory containing the source files backend:: defaults to `docbook` doctype:: defaults to `article` eruby:: defaults to erb, the version used in jruby headerFooter:: defaults to `true` compact:: defaults to `false` templateDir:: disabled by default, defaults to `null` templateEngine:: disabled by default sourceHighlighter:: enables and sets the source highlighter (currently `coderay` or `highlightjs` are supported) extensions:: a list of non-standard extensions to render separated by comma. Currently ad, adoc, and asciidoc will be rendered by default embedAssets:: embed the CSS file, etc into the output, defaults to `false` safemode:: set SAFE mode. Possible value are `safe`, `secure`, `server`, `unsafe`. Not required - default is `safe`. gemPaths:: enables to specify the location to one or more gem installation directories (same as GEM_PATH environment var), empty by default ==== Builtin attributes You can set attributes with nested ``. There are various attributes Asciidoctor recognizes. Below is a list of them and what they do : title:: An override for the title of the document. .Example [source,xml] ---- ... ... ---- Many other attributes are possible. See {asciidoctor-url}/docs/user-manual/#builtin-attributes for the full list. ==== Resources (images, css, ...) With nested ``, the external resources used by your document can be copied to output directory. .Example [source,xml] ---- ... ... ---- ==== AsciidoctorJ Extensions You can register http://asciidoctor.org/docs/asciidoctorj/#extension-api[AsciidoctorJ extensions] with nested extensions elements : [options="header",format="csv"] |=== Type, Attributes `preProcessor`, `className` `treeProcessor`, `className` `postProcessor`, `className` `blockProcessor`, `blockName` and `className` `blockMacroProcessor`, `blockName` and `className` `inlineMacroProcessor`, `blockName` and `className` `includeProcessor`, `className` |=== .Example [source,xml] ---- ... ... ---- ==== Additional Ruby libraries You can specify additional Ruby libraries not packaged in AsciidoctorJ. .Example [source,xml] ---- ... ... ---- NOTE: you have to give a path to find gems with `gempPaths` attribute.