Optionalopts: {}Describes the type of content this block accepts and how it should be converted. Acceptable values are:
compound - this block contains other blockssimple - this block holds a paragraph of prose that receives normal substitutionsverbatim - this block holds verbatim text (displayed "as is") that receives verbatim substitutionsraw - this block holds unprocessed content passed directly to the output with no substitutions appliedempty - this block has no contentGet the caption for this block. For admonition blocks, returns the 'textlabel' attribute instead.
Set the caption for this block.
Get the source file where this block started.
Get the source line number where this block started.
Provide a default logger. The Logging mixin (logging.js) overrides this getter on the prototype.
Get the value of the reftext attribute with substitutions applied. The result is pre-computed during Document.parse() via precomputeReftext. Falls back to the raw reftext attribute if precomputeReftext() has not been called yet.
the String reftext or null if not set.
Set the value of the role attribute on this node.
Accepts a single role name, a space-separated String, or an Array.
A single role name, a space-separated String, or an Array.
Get the String title of this block with title substitutions applied. The result is pre-computed during Document.parse() via precomputeTitle(). Falls back to applyHeaderSubs (sync) if precomputeTitle() has not been called yet (e.g. when a title is set via the API after parsing).
the converted String title, or null if the source title is falsy.
Set the String block title (clears the memoised converted title).
Add the given role directly to this node.
The String role name to add.
true if the role was added, false if it was already present.
Add the specified substitution to this block's substitutions list.
Get the converted alt text for this block image.
string with XML special character and replacement substitutions applied.
Append a content block to this block's list of blocks.
The new child block.
this block (enables chaining).
Generate and assign a caption to this block if not already assigned. If the block has a title and a caption prefix is available, builds a caption from the prefix and a counter, then stores it.
Optionalvalue: stringThe String caption to assign, or null to derive from document attributes.
OptionalcaptionContext: stringThe String context used to look up caption attributes.
Get the converted title prefixed with the caption.
the captioned title.
Alias for blocks — the list content.
Convert this block and return the converted String content.
the result of the converter.
Retrieve the Set of option names that are enabled on this node.
a Set of option name strings.
Walk the document tree and find all block-level nodes that match the selector and optional filter function.
The selector is a plain object whose keys narrow the search:
context {string} — node context (e.g. 'section', 'listing', 'paragraph', 'image')style {string} — block style (e.g. 'source', 'NOTE')role {string} — a CSS role that must appear in the node's role listid {string} — exact node id; stops traversal after the first matchtraverseDocuments {boolean} — when true, recurse into AsciiDoc table cellsThe optional filter function receives each candidate node and must return:
true) → include the node'prune' → include the node but do not recurse into its children'reject' → skip the node and its children'stop' → include the node (if it matched) and stop the entire traversalOptionalselector: anySelector criteria object, or a filter callback when called as findBy(callback).
Optionalfilter: FunctionPer-node filter callback.
array of matching block-level nodes.
const listings = doc.findBy({ context: 'listing', style: 'source' })
const sections = doc.findBy({ context: 'section' }, (node) => node.level <= 2 || 'prune')
Generate a data URI that embeds the image at the given local path.
The image path is cleaned to prevent access outside the jail when the document safe level is SafeMode.SAFE or higher. The image data is read and Base64-encoded. In non-Node environments this method returns an empty data URI with a warning.
A String path to the target image.
OptionalassetDirKey: stringThe String attribute key for the image directory.
a Promise resolving to a String data URI.
Read the image data from the specified URI and generate a data URI.
The image data is fetched and Base64-encoded. The MIME type is taken from the Content-Type response header.
NOTE: This method is async in JS (the Fetch API is async). When called from imageUri, the caller must await the returned Promise.
The URI from which to read the image data (http/https/ftp).
OptionalcacheUri: booleanA Boolean to control caching (not yet supported in JS).
a Promise resolving to a String data URI.
Get the converted alt text for this block image (alias of alt).
Get the value of the specified attribute.
Looks for the attribute on this node first. If not found and fallbackName is
set, and this node is not the Document node, look for that attribute on the
Document node. Otherwise, return defaultValue.
The attribute name to resolve.
OptionaldefaultValue: anyThe value to return if the attribute is not found.
OptionalfallbackName: string | booleanWhen truthy, also checks the Document's
attributes. Pass true to fall back using the same name, or a string to use a different name.
the attribute value or defaultValue.
Get the attributes hash for this node.
a plain Object of attributes.
Get the child blocks of this block.
Get the caption of this block.
Get the captioned title of this block.
Alias for the content method — mirrors the core API.
Get the content model of this block.
Get the context name for this node.
the context name.
Get the {Converter} instance being used to convert the current {Document}.
the converter instance.
Get the document to which this node belongs.
the Document.
Get the source file where this block started.
the file path, or undefined when sourcemap is disabled.
Get the icon URI for the named icon.
The String icon name.
a Promise resolving to a String URI.
Get the String id for this node.
the id, or undefined if not set.
Get the image URI for the target image.
The String target image path or URL.
OptionalassetDirKey: stringThe String asset directory attribute key.
a Promise resolving to a String URI.
Return the list items.
Get the level of this block.
Get the source line number where this block started.
line number, or undefined when sourcemap is disabled.
Get the logger for this node.
the logger instance.
Get the media URI for the target.
The String target path or URL.
OptionalassetDirKey: stringThe String asset directory attribute key.
a String URI.
Get the String name of this node.
the node name.
Get the parent node of this node.
the parent AbstractNode, or undefined for the root document.
Get the value of the reftext attribute with substitutions applied.
the reftext value, or undefined if not set.
Retrieve the space-separated String role for this node.
the role as a space-separated String.
Retrieve the String role names for this node as an Array.
the role names as a String Array, empty if the role attribute is absent.
Get the child Section blocks of this block.
Get the source location of this block.
the Cursor source location object, or undefined when sourcemap is disabled.
Get the style of this block.
Get the list of substitutions enabled for this block.
Get the title of this block with substitutions applied.
Generate cross-reference text (xreftext) used to refer to this block. Uses the explicit reftext if set. For sections or captioned blocks (blocks with both a title and a caption), formats the text according to xrefstyle. Falls back to the title, or null if no title is available.
Optionalxrefstyle: stringOptional String style: 'full', 'short', or 'basic'.
the xreftext, or null.
Check if the specified attribute is defined on this node, with optional value match and document-level fallback.
The attribute name.
OptionalexpectedValue: anyWhen truthy, also checks that the resolved value equals this.
OptionalfallbackName: string | booleanWhen truthy, also checks the Document's
attributes. Pass true to use the same name, or a string for a different fallback name.
Determine whether this block contains block content.
Check whether this list has items (blocks).
Check if the specified option attribute is enabled on this node.
This method checks whether the <name>-option attribute is set.
The String or Symbol name of the option.
true if the option is enabled, false otherwise.
Check if the reftext attribute is defined.
Check if the specified role name is present in this node's role list.
The String role name to find.
Check if the role attribute is set on this node, optionally matching an exact value.
Unlike hasRole, which checks for an individual role name within a
space-separated list, this method tests the raw role attribute string as a whole.
OptionalexpectedValue: stringWhen provided, checks that the role
attribute equals this string exactly.
Check whether this block has any child Section objects. Overridden by Document and Section.
Check whether the specified substitution is enabled for this block.
The String substitution name.
Check whether the specified substitution is enabled for this block.
Check whether the title of this block is defined.
Construct a reference or data URI to an icon image for the given name.
If the 'icon' attribute is set on this node the name is ignored and the attribute value is used as the target path. Otherwise the icon path is built from 'iconsdir', the name, and 'icontype' (default: 'png').
The String name of the icon.
a Promise resolving to a String reference or data URI for the icon image.
Construct a URI reference or data URI to the target image.
If the target image is already a URI it is left untouched (unless data-uri conversion is requested). The image is resolved relative to the directory named by assetDirKey. When data-uri is enabled and the safe level permits, the image is embedded as a Base64 data URI.
NOTE: When the document has both 'data-uri' and 'allow-uri-read' enabled and the resolved image URL is a remote URI, this method returns a Promise rather than a String. Await the result when that combination may be active.
A String path to the target image.
OptionalassetDirKey: stringThe String attribute key for the image directory.
a Promise resolving to a String reference or data URI.
Check if the specified attribute is defined with an optional value match. Alias for hasAttribute.
OptionalexpectedValue: anyCheck whether this node has reftext — either an explicit 'reftext' attribute or a title that can serve as the cross-reference text. Mirrors Ruby's AbstractNode#reftext?
Get the list marker keyword for the specified list type.
OptionallistType: stringThe String list type (default: this.style).
the single-character String keyword for the list marker.
Construct a URI reference to the target media.
A String reference to the target media.
OptionalassetDirKey: stringThe String attribute key for the media directory.
a String reference for the target media.
Move to the next adjacent block in document order. If the current block is the last item in a list, returns the following sibling of the list block.
the next AbstractBlock, or null.
Normalize the asset file or directory to a concrete and rinsed path.
Delegates to normalizeSystemPath with start set to document.baseDir.
The String asset reference to normalize.
OptionalassetName: stringThe String label for the asset used in messages.
Optionalautocorrect: booleanA Boolean indicating whether to recover from an illegal path.
the normalized String path.
Resolve and normalize a secure path from the target and start paths.
Prevents resolving a path outside the jail (defaulting to document.baseDir) when the document safe level is SafeMode.SAFE or higher.
The String target path.
Optionalstart: stringThe String start (parent) path.
Optionaljail: stringThe String jail path.
Optionalopts: anyA plain object of options:
recover {boolean} - Whether to automatically recover for illegal paths.targetName {string} - Label used in messages for the path being resolved.the resolved String path.
Normalize the web path using the PathResolver.
The String target path.
Optionalstart: stringThe String start (parent) path.
OptionalpreserveUriTarget: booleanWhether a URI target should be preserved as-is.
the resolved String path.
Check whether this list is an outline list (unordered or ordered).
Pre-compute the reftext with substitutions applied asynchronously. Called during Document.parse() so the synchronous getter works during conversion.
Pre-compute the converted title asynchronously. Called during Document.parse() so the synchronous getter works during conversion. Re-entrant calls (circular title references) are detected via _computingTitle and silently skipped so that () can return null (→ "[refid]" fallback).
Read the contents of the file at the specified path.
This method checks that the file is readable before attempting to read it.
The String path from which to read the contents.
Optionalopts: anyA plain object of options:
warnOnFailure {boolean} - Whether a warning is issued when the file cannot be read (default: false).normalize {boolean} - Whether lines are normalized and coerced to UTF-8 (default: false).label {string} - Label for the file used in warning messages.a Promise resolving to the file content, or null if not readable.
Resolve the URI or system path to the target, then read and return its contents.
When the resolved path is a URI and allow-uri-read is enabled, the content is fetched via the Fetch API (async). When it is a local path, the file is read via readAsset.
The URI or local path String from which to read the data.
Optionalopts: anyA plain object of options:
label {string} - Label used in warning messages (default: 'asset').normalize {boolean} - Whether the data should be normalized (default: false).start {string} - Relative base path for resolving the target.warnOnFailure {boolean} - Whether warnings are issued on failure (default: true).warnIfEmpty {boolean} - Whether a warning is issued when the target contents are empty (default: false).a Promise resolving to the content, or null on failure.
Remove the attribute from this node.
The attribute name to remove.
the previous value, or undefined if the attribute was not present.
Remove the given role directly from this node.
The String role name to remove.
true if the role was removed, false if it was not present.
Remove a substitution from this block.
The String substitution name to remove.
Remove the specified substitution from this block's substitutions list.
Get the child Section objects of this block. Only applies to Document and Section instances.
array of Section objects (may be empty).
Set the value of the specified attribute on this node.
The attribute name to assign.
Optionalvalue: anyThe value to assign.
Optionaloverwrite: booleanWhen false, does nothing if the attribute already exists.
true if the attribute was set, false if blocked by overwrite=false.
Subclasses (e.g. Document) may return the resolved value string or null when the attribute is locked.
Set the caption of this block.
Set the content model of this block.
Update the context of this block, also updating the node name.
The String context to assign to this block.
Set the String id for this node.
The String id to assign.
Set the level of this block.
Set the specified option on this node by setting the <name>-option attribute.
The String name of the option.
Set the parent of this node. Also updates the document reference.
Set the value of the role attribute on this node.
Accepts a single role name, a space-separated String, an Array, or spread arguments.
A single role name, a space-separated String, an Array, or multiple role names as spread arguments.
the value of the role attribute.
Set the style of this block.
Set the raw title of this block.
Update the attributes of this node with the new values.
A plain object of additional attributes to assign.
the updated attributes object on this node.
Alias for getXrefText.
Optionalxrefstyle: stringOptional String style: 'full', 'short', or 'basic'.
the xreftext, or null.
Array of AbstractBlock child blocks for this block. Only applies if content model is
compound.