API Options

Name Description Default value Allowed values

Name	Description	Default value	Allowed values
`:attributes`	Sets document attributes, which override equivalently-named attributes defined in the document unless soft set. No substitutions are applied to the value of these attributes. In the hash format, a `nil` value hard unsets the attribute and a `false` value soft unsets the attribute.	not set	Document attributes in the following formats: Hash `{ 'name' => 'value' }` Array `[ 'name=value' ]` String (space separated) `'name=value'`
`:backend`	Selects converter to use.	`html5`	`html5`, `docbook5`, `manpage`, or a backend mapped to an available converter
`:base_dir`	Sets the base (aka working) directory containing the document and resources.	Directory of the source file, or the working directory if the source is read from a stream.	file path
`:catalog_assets`	If `true`, the parser captures 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).	`false`	Boolean
`:converter`	Specifies a user-supplied converter class or instance, used in place of the converter that is automatically resolved from the `backend` value.	not set	`Asciidoctor::Converter` class or instance
`:doctype`	Sets the document type.	`article`	`article`, `book`, `manpage`, `inline`
`:eruby`	Specifies the eRuby implementation to use for executing the converter templates written in ERB.	`erb`	`erb`, `erubis`
`:extensions`	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).
`:extension_registry`	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
`:header_only`	If `true`, the parser stops after reading the header.	`false`	Boolean
`:standalone`	If `true`, generates a standalone output document (which includes the shell around the body content, such as the header and footer). When converting to a file, the default value is `true`. Otherwise, the default value is `false`. The deprecated alias for this option is `:header_footer`. The default value for this option is opposite of the default value for the CLI.	Varies	Boolean
`:mkdirs`	If `true`, the processor creates the necessary output directories if they don’t yet exist.	`false`	Boolean
`:parse`	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.	`true`	Boolean
`:safe`	Sets the safe mode.	`:secure`	`:unsafe`, `:safe`, `:server`, `:secure`
`:sourcemap`	Tracks 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.	`false`	Boolean
`:template_cache`	Enables the built-in cache used by the template converter when reading the source of template files. Only relevant if `:template_dirs` is specified.	`true`	Boolean
`:template_dirs`	Array of directories containing Tilt-compatible converter templates to be used instead of the default built-in templates.	not set	Array of file paths
`:template_engine`	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.	auto (Set based on the file extension of the custom converter templates found).	Template engine name (e.g., `slim`, `haml`, `erb`, etc.)
`:template_engine_options`	Low-level options passed directly to the template engine.	not set	Nested Hash of options with the template engine name as the top-level key and the option name as the second-level key.
`:timings`	Capture time taken to read, parse, and convert document. Internal use only.	not set	`Asciidoctor::Timings` instance
`:to_file`	Name of the output file to write, or `true` to use the default output file (`docname` + `outfilesuffix`).	not set	`true`, file path
`:to_dir`	Destination directory for output file(s), relative to `base_dir`.	Directory containing source file, or working directory if source is read from a stream.	File path

:attributes

Sets document attributes, which override equivalently-named attributes defined in the document unless soft set. No substitutions are applied to the value of these attributes. In the hash format, a nil value hard unsets the attribute and a false value soft unsets the attribute.

not set

Document attributes in the following formats:

Hash
{ 'name' => 'value' }

Array
[ 'name=value' ]

String (space separated)
'name=value'

:backend

Selects converter to use.

html5

html5, docbook5, manpage, or a backend mapped to an available converter

:base_dir

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

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

file path

:catalog_assets

If true, the parser captures 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).

false

Boolean

:converter

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

not set

Asciidoctor::Converter class or instance

:doctype

Sets the document type.

article

article, book, manpage, inline

:eruby

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

erb

erb, erubis

:extensions

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).

:extension_registry

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

:header_only

If true, the parser stops after reading the header.

false

Boolean

:standalone

If true, generates a standalone output document (which includes the shell around the body content, such as the header and footer). When converting to a file, the default value is true. Otherwise, the default value is false. The deprecated alias for this option is :header_footer. The default value for this option is opposite of the default value for the CLI.

Varies

Boolean

:mkdirs

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

false

Boolean

:parse

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.

true

Boolean

:safe

Sets the safe mode.

:secure

:unsafe, :safe, :server, :secure

:sourcemap

Tracks 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.

false

Boolean

:template_cache

Enables the built-in cache used by the template converter when reading the source of template files. Only relevant if :template_dirs is specified.

true

Boolean

:template_dirs

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

not set

Array of file paths

:template_engine

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.

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

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

:template_engine_options

Low-level options passed directly to the template engine.

not set

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

:timings

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

not set

Asciidoctor::Timings instance

:to_file

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

not set

true, file path

:to_dir

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

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

File path