1.5.9Methods for parsing AsciiDoc input files and converting documents.
AsciiDoc documents comprise a header followed by zero or more sections. Sections are composed of blocks of content. For example:
= Doc Title == Section 1 This is a paragraph block in the first section. == Section 2 This section has a paragraph block and an olist block. . Item 1 . Item 2
asciidoctor.convertFile('sample.adoc');
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)
(any)
(any)
(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
(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.
Get the file associated to the cursor.
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)
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.