Name
cx:asciidoctor — Convert Asciidoctor documents.
Synopsis
The cx:asciidoctor step converts Asciidoctor documents to DocBook,
HTML5, or PDF.
| Input port | Primary | Sequence | Content types |
|---|---|---|---|
| source | ✔ | text/asciidoc text |
| Output port | Primary | Sequence | Content types |
|---|---|---|---|
| result | ✔ | xml html application/pdf |
| Option name | Type | Values | Default value |
|---|---|---|---|
| attributes | map(xs:QName, item()*)? | () | |
| backend | xs:string? | ('docbook', 'html5', 'pdf') | () |
| parameters | map(xs:QName, item()*)? | () |
<p:import href="https://xmlcalabash.com/ext/library/asciidoctor.xpl"/>Declaration
1 |<p:declare-step xmlns:cx="http://xmlcalabash.com/ns/extensions"
| xmlns:p="http://www.w3.org/ns/xproc"
| type="cx:asciidoctor">
| <p:input port="source" content-types="text/asciidoc text"/>
5 | <p:output port="result" content-types="xml html application/pdf"/>
| <p:option name="backend" as="xs:string?" values="('docbook', 'html5', 'pdf')"/>
| <p:option name="parameters" as="map(xs:QName, item()*)?"/>
| <p:option name="attributes" as="map(xs:QName, item()*)?"/>
|</p:declare-step>Description
Asciidoctor is the modern toolchain for processing Asciidoc markup. Asciidoc is a sophisticated lightweight markup language that can be used to represent complex structures. One of its original goals was to capture DocBook in a markdown-like style. Asciidoc predates Markdown.
The Java API that XML Calabash uses, AsciidoctorJ, offers both options and attributes. In fact, the attributes are part of the options API. It all seems a bit confused to me.
For the step, I’ve implemented options in the parameters option and
attributes in the attributes option.
Parameters
The parameters listed below are supported. These are passed directly to the Asciidoctor API; please consult the API for more details.
| Parameter | Type | Notes |
|---|---|---|
base_dir | xs:string | Must be the name of a directory. |
backend | xs:string | Must be the same as the backend option, if both are specified. |
catalog_assets | xs:boolean | |
doctype | xs:string | |
standalone | xs:boolean | |
template_dirs | xs:string* | Must be directory names |
template_engine | xs:string | |
template_cache | xs:boolean | |
safe | xs:string | “unsafe”, “safe”,
“server”, or “secure” |
sourcemap | xs:boolean | |
eruby | xs:string | |
compact | xs:boolean | |
parse_header_only | xs:boolean |
Attributes
The attributes listed below are supported. These are passed directly to the Asciidoctor API; please consult the API for more details.
There were errors in this table as initial published. The names of many attributes were corrected in the documentation for XML Calabash 3.0.49. Most of the errors were related to the presence of underscores or hyphens, but note that the “math” attribute is actually named “stem”.
| Parameter | Type | Notes |
|---|---|---|
allow-uri-read | xs:boolean | |
appendix-caption | xs:string | |
attribute-missing | xs:string | |
attribute-undefined | xs:string | |
backend | xs:string | |
compat-mode | xs:string | “default” or “legacy” |
data-uri | xs:boolean | |
docdate | xs:dateTime | |
doctime | xs:dateTime | |
doctype | xs:string | |
experimental | xs:boolean | |
hardbreaks | xs:boolean | |
hide-uri-scheme | xs:boolean | |
iconfont-cdn | xs:anyURI | |
iconfont-name | xs:string | |
iconfont-remote | xs:boolean | |
icons | xs:string | |
iconsdir | xs:string | |
ignore-undefined | xs:boolean | |
imagesdir | xs:string | |
linkattrs | xs:boolean | |
linkcss | xs:boolean | |
localdate | xs:dateTime | |
localtime | xs:dateTime | |
max-include-depth | xs:int | |
nofooter | xs:boolean | |
sectnums | xs:boolean | |
sectnumlevels | xs:int | |
sectanchors | xs:boolean | |
showtitle | xs:boolean | |
skip-front-matter | xs:boolean | |
source-highlighter | xs:string | |
source-language | xs:string | |
stem | xs:string | |
stylesheet | xs:string | |
stylesdir | xs:string | |
title | xs:string | |
toc | xs:string | “true”, “false”,
“top”, “bottom”, “left”,
“right”, “preamble”, or
“macro” |
untitled-label | xs:string |
Dependencies
This step is included in the XML Calabash application. If you are getting XML Calabash from Maven, you will also need to include the extension dependencies:
org.asciidoctor:asciidoctorj:3.0.1org.asciidoctor:asciidoctorj-pdf:2.3.23
Additional examples
The XML Calabash test suite contains examples of the cx:asciidoctor step.