Convert options

This document describes the list of options you can use when converting a document.

Name Description Default value Allowed values

Name	Description	Default value	Allowed values
`attributes`	Sets additional document attributes, which override equivalently-named attributes defined in the document unless the value ends with `@`.	not set	Any number of built-in or user-defined attributes in one of the following formats: JSON: `{'name': 'value'}` Array: `['name=value']` String: `'name=value'`
`backend`	Selects the converter to use (as registered with this keyword).	html5	html5, docbook5, or any backend registered through an active converter
`base_dir`	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
`catalog_assets`	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).	false	boolean
`doctype`	Sets the document type.	article	article, book, manpage or inline
`extensions_registry`	Overrides the extensions registry instance. Instead of providing a JavaScript function 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
`mkdirs`	If true, the processor will create 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 `loadFile` API). If false, parsing is deferred until the `parse` method is explicitly invoked.	true	boolean
`safe`	Sets the safe mode. Disables potentially dangerous macros in source files, such as `include::[]`.	secure	unsafe, safe, server or secure
`sourcemap`	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).	false	boolean
`standalone`	If true, add the document header and footer (i.e., framing) around the body content in the output.	false	boolean
`template_dirs`	An array of directories containing templates to be used instead of the default built-in templates.	not set	An array of file paths
`to_dir`	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
`to_file`	The name of the output file to write, or true to use the default output file (`docname` + `outfilesuffix`).	not set	true, file path

attributes

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

not set

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

JSON:
{'name': 'value'}
Array:
['name=value']
String:
'name=value'

backend

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

html5

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

base_dir

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

catalog_assets

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

false

boolean

doctype

Sets the document type.

article

article, book, manpage or inline

extensions_registry

Overrides the extensions registry instance. Instead of providing a JavaScript function 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

mkdirs

If true, the processor will create 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 loadFile API). If false, parsing is deferred until the parse method is explicitly invoked.

true

boolean

safe

Sets the safe mode.
Disables potentially dangerous macros in source files, such as include::[].

secure

unsafe, safe, server or secure

sourcemap

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

false

boolean

standalone

If true, add the document header and footer (i.e., framing) around the body content in the output.

false

boolean

template_dirs

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

not set

An array of file paths

to_dir

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

to_file

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

not set

true, file path

Usage

In the following example, we define the safe option to unsafe and we also define two attributes:

showtitle: display the title of an embedded document
icons: use font icons instead of text for admonitions

var content = '= Document title'
var html = asciidoctor.convert(content, { 'safe': 'server', 'attributes': { 'showtitle': true, 'icons': 'font' } })
console.log(html)
// <h1>Document title</h1>

You can read more about document attributes on asciidoctor.org/docs/user-manual/#attribute-catalog