Ruby API Options

Name Description Default value Allowed values CLI equivalent


Sets additional document attributes, which override equivalently-named attributes defined in the document unless the value ends with @.

not set

Any number of builtin-attributes,built-in or user-defined attributes in one of the following formats:


-a, --attributes


Selects the converter to use (as registered with this keyword).


html5, docbook5, manpage, or any backend registered through an active converter

-b, --backend


Sets the base (aka working) directory containing the document and resources.

The directory of the source file, or the working directory if the source is read from a stream.

file path

-B, --base-dir


If true, tells the parser to capture images and links in the reference table. (Normally only IDs, footnotes and indexterms are included). The reference table is available via the references property on the document AST object. (Experimental).





Specifies a user-supplied Asciidoctor::Converter instance, used in place of the converter that is automatically resolved from the backend value.

not set

Asciidoctor::Converter instance

n/a (Can be emulated using a combination of -r and -b).


Sets the document type.


article, book, manpage, inline

-d, --doctype


Specifies the eRuby implementation to use for executing the converter templates written in ERB.


erb, erubis

-e, --eruby


A Ruby block that registers (and possibly defines) Asciidoctor extensions for this instance of the processor.

not set

A Ruby block that conforms to the Asciidoctor extensions API (the same code that would be passed to the Extensions.register method).

n/a (Can be emulated using -r).


Overrides the extensions registry instance. Instead of providing a Ruby block containing extensions to register, this option lets you replace the extension registry itself, giving you complete control over how extensions are registered for this processor.

not set

Extensions::Registry instance



If true, add the document header and footer (i.e., framing) around the body content in the output. NOTE: The default value for this option is opposite of the default value for the CLI.



-s, --no-header-footer


If true, the processor will create the necessary output directories if they don’t yet exist.



n/a (Implicitly enabled).


If true, the source is parsed eagerly (i.e., as soon as the source is passed to the load or load_file API). If false, parsing is deferred until the parse method is explicitly invoked.





Sets the safe mode.


:unsafe, :safe, :server, :secure

-S, --safe-mode


Keeps track of the file and line number for each parsed block. (Useful for tooling applications where the association between the converted output and the source file is important).





If true, enables the built-in cache used by the template converter when reading the source of template files. Only relevant if the :template_dirs option is specified.





Specifies a directory of Tilt-compatible templates to be used instead of the default built-in templates. Deprecated. Please use :template_dirs instead.

not set

file path

-T, --template-dir


An array of directories containing Tilt-compatible converter templates to be used instead of the default built-in templates.

not set

An array of file paths

-T, --template-dir


Template engine to use for the custom converter templates. The gem with the same name as the engine will be loaded automatically. This name is also used to build the full path to the custom converter templates.

(Set based on the file extension of the custom converter templates found).

Template engine name (e.g., slim, haml, erb, etc.)

-E, --template-engine


Low-level options passed directly to the template engine.

not set

A nested Hash of options with the template engine name as the top-level key and the option name as the second-level key.



Capture time taken to read, parse, and convert document. Internal use only.

not set

Asciidoctor::Timings instance

-t, --timings


The name of the output file to write, or true to use the default output file (docname + outfilesuffix).

not set

true, file path

-o, --out-file


Destination directory for output file(s), relative to base_dir.

The directory containing the source file, or the working directory if the source is read from a stream.

file path

-D, --destination-dir