2.0.3The main application interface (API) for Asciidoctor. This API provides methods to parse AsciiDoc content and convert it to various output formats using built-in or third-party converters.
An AsciiDoc document can be as simple as a single line of content, though it more commonly starts with a document header that declares the document title and document attribute definitions. The document header is then followed by zero or more section titles, optionally nested, to organize the paragraphs, blocks, lists, etc. of the document.
By default, the processor converts the AsciiDoc document to HTML 5 using a built-in converter. However, this behavior can be changed by specifying a different backend (e.g., +docbook+). A backend is a keyword for an output format (e.g., DocBook). That keyword, in turn, is used to select a converter, which carries out the request to convert the document to that format.
asciidoctor.convertFile('document.adoc', { 'safe': 'safe' }) // Convert an AsciiDoc file
asciidoctor.convert("I'm using *Asciidoctor* version {asciidoctor-version}.", { 'safe': 'safe' }) // Convert an AsciiDoc string
const doc = asciidoctor.loadFile('document.adoc', { 'safe': 'safe' }) // Parse an AsciiDoc file into a document object
const doc = asciidoctor.load("= Document Title\n\nfirst paragraph\n\nsecond paragraph", { 'safe': 'safe' }) // Parse an AsciiDoc string into a document object
Parse the AsciiDoc source input into an Document and convert it to the specified backend format.
Accepts input as a Buffer or String.
(Object)
a JSON of options to control processing (default: {})
(string | Document):
returns the
Document
object if the converted String is written to a file,
otherwise the converted String
var input = '= Hello, AsciiDoc!\n' +
'Guillaume Grossetie <ggrossetie@example.com>\n\n' +
'An introduction to http://asciidoc.org[AsciiDoc].\n\n' +
'== First Section\n\n' +
'* item 1\n' +
'* item 2\n';
var html = asciidoctor.convert(input);
Parse the AsciiDoc source input into an Document and convert it to the specified backend format.
(string)
source filename
(Object)
a JSON of options to control processing (default: {})
(string | Document):
returns the
Document
object if the converted String is written to a file,
otherwise the converted String
var html = asciidoctor.convertFile('./document.adoc');
Extends AbstractNode
Append a block to this block's list of child blocks.
(any)
AbstractBlock:
the parent block to which this block was appended.
Get the String title of this Block with title substitions applied
The following substitutions are applied to block and section titles:
specialcharacters, quotes, replacements, macros, attributes and post_replacements
string:
returns the converted String title for this Block, or undefined if the title is not set.
block.title // "Foo 3^ # {two-colons} Bar(1)"
block.getTitle(); // "Foo 3^ # :: Bar(1)"
Convenience method that returns the interpreted title of the Block with the caption prepended. Concatenates the value of this Block's caption instance variable and the return value of this Block's title method. No space is added between the two values. If the Block does not have a caption, the interpreted title is returned.
string:
the converted String title prefixed with the caption, or just the
converted String title if no caption is set
Remove the specified substitution keyword from the list of substitutions for this block.
(any)
any:
undefined
Checks if the AbstractBlock contains any child blocks.
boolean:
whether the
AbstractBlock
has child blocks.
Get the list of AbstractBlock sub-blocks for this block.
Array:
returns a list of
AbstractBlock
sub-blocks
Query for all descendant block-level nodes in the document tree that match the specified selector (context, style, id, and/or role). If a function block is given, it's used as an additional filter. If no selector or function block is supplied, all block-level nodes in the tree are returned.
Array:
returns a list of block-level nodes that match the filter or an empty list if no matches are found
doc.findBy({'context': 'section'});
// => { level: 0, title: "Hello, AsciiDoc!", blocks: 0 }
// => { level: 1, title: "First Section", blocks: 1 }
doc.findBy({'context': 'section'}, function (section) { return section.getLevel() === 1; });
// => { level: 1, title: "First Section", blocks: 1 }
doc.findBy({'context': 'listing', 'style': 'source'});
// => { context: :listing, content_model: :verbatim, style: "source", lines: 1 }
Get the numeral of this block (if section, relative to parent, otherwise absolute). Only assigned to section if automatic section numbering is enabled. Only assigned to formal block (block with title) if corresponding caption attribute is present. If the section is an appendix, the numeral is a letter (starting with A).
string:
returns the numeral
Set the numeral of this block.
(any)
A convenience method that checks whether the title of this block is defined.
any:
a {boolean} indicating whether this block has a title.
Extends AbstractBlock
Set the 0-based index order of this section within the parent block.
(any)
Set the section name of this section.
(any)
Set the flag to indicate whether this is a special section or a child of one.
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
Get the AbstractNode to which this node is attached.
AbstractNode:
returns the
AbstractNode
object to which this node is attached,
or undefined if this node has no parent.
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
Read the contents of the file at the specified path. This method assumes that the path is safe to read. It checks that the file is readable before attempting to read it
(any)
the {string} path from which to read the contents
(any)
a JSON {Object} of options to control processing (default: {})
any:
the {string} content of the file at the specified path, or undefined if the file does not exist.
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
The Document class represents a parsed AsciiDoc document.
Document is the root node of a parsed AsciiDoc document.
It provides an abstract syntax tree (AST) that represents the structure of the AsciiDoc document
from which the Document object was parsed.
Although the constructor can be used to create an empty document object, more commonly, you'll load the document object from AsciiDoc source using the primary API methods on Asciidoctor. When using one of these APIs, you almost always want to set the safe mode to 'safe' (or 'unsafe') to enable all of Asciidoctor's features.
var doc = Asciidoctor.load('= Hello, AsciiDoc!', { 'safe': 'safe' })
// => Asciidoctor::Document { doctype: "article", doctitle: "Hello, AsciiDoc!", blocks: 0 }
Instances of this class can be used to extract information from the document or alter its structure. As such, the Document object is most often used in extensions and by integrations.
The most basic usage of the Document object is to retrieve the document's title.
var source = '= Document Title'
var doc = asciidoctor.load(source, { 'safe': 'safe' })
console.log(doc.getTitle()) // 'Document Title'
You can also use the Document object to access document attributes defined in the header, such as the author and doctype.
Extends AbstractBlock
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
Document/Title:
returns a
Document/Title
Get the document catalog Hash.
Get the document revision date from document header (document attribute revdate).
Get the document revision number from document header (document attribute revnumber).
Get the document revision remark from document header (document attribute revremark).
Assign a value to the specified attribute in the document header.
The assignment will be visible when the header attributes are restored, typically between processor phases (e.g., between parse and convert).
(string)
The {string} attribute name to assign
(Object)
The {Object} value to assign to the attribute (default: '')
(boolean)
A {boolean} indicating whether to assign the attribute
if already present in the attributes Hash (default: true)
boolean:
returns true if the assignment was performed otherwise false
Document/RevisionInfo:
returns a
Document/RevisionInfo
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
Get the document revision date from document header (document attribute revdate).
Get the document revision number from document header (document attribute revnumber).
Get the document revision remark from document header (document attribute revremark).
A short summary of changes in this document revision.
Extends AbstractNode
Set the String source text of this ListItem node.
(any)
(any)
(any)
(any)
(any)
(any)
Get the current location of the reader's cursor, which encapsulates the file, dir, path, and lineno of the file being read.
Check whether there are any lines left to read. If a previous call to this method resulted in a value of false, immediately returned the cached value. Otherwise, delegate to peekLine to determine if there is a next line available.
boolean:
returns true if there are more lines, false if there are not.
Peek at the next line. Processes the line if not already marked as processed, but does not consume it (ie. you will be able to read this line again).
This method will probe the reader for more lines. If there is a next line that has not previously been visited, the line is passed to the Reader#processLine method to be initialized. This call gives sub-classes the opportunity to do preprocessing. If the return value of the Reader#processLine is undefined, the data is assumed to be changed and Reader#peekLine is invoked again to perform further processing.
If hasMoreLines is called immediately before peekLine, the direct flag is implicitly true (since the line is flagged as visited).
(boolean)
A {boolean} flag to bypasses the check for more lines and immediately returns the first element of the internal lines {Array}. (default: false)
string:
returns the next line as a {string} if there are lines remaining.
Consume, preprocess, and return the remaining lines.
This method calls Reader#readLine repeatedly until all lines are consumed and returns the lines as an {Array} of {string}. This method differs from Reader#getLines in that it processes each line in turn, hence triggering any preprocessors implemented in sub-classes.
Lines will be consumed from the Reader (ie. you won't be able to read these lines again).
Array:
returns the lines read as an {Array} of {string}.
Get the file associated to the cursor.
This API is experimental and subject to change.
A pluggable adapter for integrating a syntax (aka code) highlighter into AsciiDoc processing.
There are two types of syntax highlighter adapters. The first performs syntax highlighting during the convert phase. This adapter type must define a "handlesHighlighting" method that returns true. The companion "highlight" method will then be called to handle the "specialcharacters" substitution for source blocks.
The second assumes syntax highlighting is performed on the client (e.g., when the HTML document is loaded). This adapter type must define a "hasDocinfo" method that returns true. The companion "docinfo" method will then be called to insert markup into the output document. The docinfo functionality is available to both adapter types.
Asciidoctor.js provides several a built-in adapter for highlight.js. Additional adapters can be registered using SyntaxHighlighter.register.
This API is experimental and subject to change.
Extensions provide a way to participate in the parsing and converting phases of the AsciiDoc processor or extend the AsciiDoc syntax.
The various extensions participate in AsciiDoc processing as follows:
Extensions may be registered globally using the {Extensions.register} method or added to a custom {Registry} instance and passed as an option to a single Asciidoctor processor.
Opal.Asciidoctor.Extensions.register(function () {
this.block(function () {
var self = this;
self.named('shout');
self.onContext('paragraph');
self.process(function (parent, reader) {
var lines = reader.getLines().map(function (l) { return l.toUpperCase(); });
return self.createBlock(parent, 'paragraph', lines);
});
});
});
Create a new Extensions/Registry.
Extensions/Registry:
returns a
Extensions/Registry
(any)
(any)
Get statically-registerd extension groups.
Unregister all statically-registered extension groups.
Unregister the specified statically-registered extension groups.
NOTE Opal cannot delete an entry from a Hash that is indexed by symbol, so we have to resort to using low-level operations in this method.
this API is experimental and subject to change
(any)
(any)
this API is experimental and subject to change
(any)
(any)
this API is experimental and subject to change
(any)
(any)
this API is experimental and subject to change
(any)
(any)
this API is experimental and subject to change
(any)
(any)
this API is experimental and subject to change
(any)
(any)
this API is experimental and subject to change
(any)
(any)
this API is experimental and subject to change
(any)
(any)
this API is experimental and subject to change
(any)
(any)
this API is experimental and subject to change
(any)
(any)
this API is experimental and subject to change
(any)
(any)
this API is experimental and subject to change
(any)
(any)
this API is experimental and subject to change
(any)
(any)
this API is experimental and subject to change
(any)
(any)
this API is experimental and subject to change
(any)
(any)
this API is experimental and subject to change
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
Checks whether any {Extensions/Preprocessor} extensions have been registered.
any:
a {boolean} indicating whether any {
Extensions/Preprocessor
} extensions are registered.
Checks whether any {Extensions/TreeProcessor} extensions have been registered.
any:
a {boolean} indicating whether any {
Extensions/TreeProcessor
} extensions are registered.
Checks whether any {Extensions/IncludeProcessor} extensions have been registered.
any:
a {boolean} indicating whether any {
Extensions/IncludeProcessor
} extensions are registered.
Checks whether any {Extensions/Postprocessor} extensions have been registered.
any:
a {boolean} indicating whether any {
Extensions/Postprocessor
} extensions are registered.
Checks whether any {Extensions/DocinfoProcessor} extensions have been registered.
(any)
A {string} for selecting docinfo extensions at a given location (head or footer) (default: undefined)
any:
a {boolean} indicating whether any {
Extensions/DocinfoProcessor
} extensions are registered.
Checks whether any {Extensions/BlockProcessor} extensions have been registered.
any:
a {boolean} indicating whether any {
Extensions/BlockProcessor
} extensions are registered.
Checks whether any {Extensions/BlockMacroProcessor} extensions have been registered.
any:
a {boolean} indicating whether any {
Extensions/BlockMacroProcessor
} extensions are registered.
Checks whether any {Extensions/InlineMacroProcessor} extensions have been registered.
any:
a {boolean} indicating whether any {
Extensions/InlineMacroProcessor
} extensions are registered.
Retrieves the Extension proxy objects for all the {Extensions/Preprocessor} instances stored in this registry.
any:
an {array} of Extension proxy objects.
Retrieves the Extension proxy objects for all the {Extensions/TreeProcessor} instances stored in this registry.
any:
an {array} of Extension proxy objects.
Retrieves the Extension proxy objects for all the {Extensions/IncludeProcessor} instances stored in this registry.
any:
an {array} of Extension proxy objects.
Retrieves the Extension proxy objects for all the {Extensions/Postprocessor} instances stored in this registry.
any:
an {array} of Extension proxy objects.
Retrieves the Extension proxy objects for all the {Extensions/DocinfoProcessor} instances stored in this registry.
(any)
A {string} for selecting docinfo extensions at a given location (head or footer) (default: undefined)
any:
an {array} of Extension proxy objects.
Retrieves the Extension proxy objects for all the {Extensions/BlockProcessor} instances stored in this registry.
any:
an {array} of Extension proxy objects.
Retrieves the Extension proxy objects for all the {Extensions/BlockMacroProcessor} instances stored in this registry.
any:
an {array} of Extension proxy objects.
Retrieves the Extension proxy objects for all the {Extensions/InlineMacroProcessor} instances stored in this registry.
any:
an {array} of Extension proxy objects.
Get any {Extensions/InlineMacroProcessor} extensions are registered to handle the specified inline macro name.
(any)
the {string} inline macro name
any:
the Extension proxy object for the {
Extensions/InlineMacroProcessor
} that matches the inline macro name or undefined if no match is found.
Get any {Extensions/BlockProcessor} extensions are registered to handle the specified block name appearing on the specified context.
(any)
the {string} block name
(any)
the context of the block: paragraph, open... (optional)
any:
the Extension proxy object for the {
Extensions/BlockProcessor
} that matches the block name and context or undefined if no match is found.
Get any {Extensions/BlockMacroProcessor} extensions are registered to handle the specified macro name.
(any)
the {string} macro name
any:
the Extension proxy object for the {
Extensions/BlockMacroProcessor
} that matches the macro name or undefined if no match is found.
The extension will be added to the beginning of the list for that extension type. (default is append).
prefer
function on the
Extensions/Registry
,
the
Extensions/IncludeProcessor
,
the
Extensions/TreeProcessor
,
the
Extensions/Postprocessor
,
the
Extensions/Preprocessor
or the
Extensions/DocinfoProcessor
(any)
(any)
(any)
(any)
(any)
(any)
(any)
Creates a list block node and links it to the specified parent.
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
(any)
Convert the specified node.
(AbstractNode)
the AbstractNode to convert
(string)
an optional String transform that hints at
which transformation should be applied to this node.
(Object)
a JSON of options that provide additional hints about
how to convert the node (default: {})
any:
the {Object} result of the conversion, typically a {string}.
Register a custom converter in the global converter factory to handle conversion to the specified backends. If the backend value is an asterisk, the converter is used to handle any backend that does not have an explicit converter.
(any)
The Converter instance to register
(any)
{Array} - A {string} {Array} of backend names that this converter should be registered to handle (optional, default:
['*']
)
any:
Returns nothing
Retrieves the singleton instance of the converter factory.
(boolean)
instantiate the singleton if it has not yet
been instantiated. If this value is false and the singleton has not yet been
instantiated, this method returns a fresh instance.
Converter/Factory:
an instance of the converter factory.