@asciidoctor/core

3.0.0-dev

The 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
Example
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
Static Members
getCoreVersion()
getRuntime()
convert(input, options)
convertFile(filename, options)
load(input, options)
loadFile(filename, options)
getVersion()
getVersion()
AbstractBlock

Extends AbstractNode

Static Members
append(block)
getTitle()
setTitle(title)
assignCaption(value, captionContext)
getCaptionedTitle()
getStyle()
setStyle(style)
getSourceLocation()
getCaption()
setCaption(caption)
getLevel()
getSubstitutions()
hasSubstitution(substitution)
removeSubstitution(substitution)
hasBlocks()
getBlocks()
getContent()
convert()
findBy(selector?, block?)
getLineNumber()
hasSections()
getSections()
getNumeral()
setNumeral(value)
hasTitle()
getAlt()
setLevel(level)

Methods for managing sections of AsciiDoc content in a document.

Section

Extends AbstractBlock

Example
<pre>
  section = asciidoctor.Section.create()
  section.setTitle('Section 1')
  section.setId('sect1')
  section.getBlocks().length // 0
  section.getId() // "sect1"
  section.append(newBlock)
  section.getBlocks().length // 1
</pre>
Static Members
create(parent?, level?, numbered?, opts?)
getIndex()
setIndex(index)
getSectionName()
setSectionName(value)
isSpecial()
setSpecial(value)
isNumbered()
getCaption()
getName()

Methods for managing AsciiDoc content blocks.

Block

Extends AbstractBlock

Example
block = asciidoctor.Block.create(parent, 'paragraph', {source: '_This_ is a <test>'})
block.getContent()
// "<em>This</em> is a &lt;test&gt;"
Static Members
create(parent, context, opts?)
getSource()
getSourceLines()

An abstract base class that provides state and methods for managing a node of AsciiDoc content. The state and methods on this class are common to all content segments in an AsciiDoc document.

AbstractNode
Static Members
applySubstitutions(text, subs?)
resolveSubstitutions(subs, type?, defaults?, subject?)
getNodeName()
getAttributes()
getAttribute(name, defaultValue?, fallbackName?)
hasAttribute(name)
isAttribute(name, expectedValue?, fallbackName)
setAttribute(name, value, overwrite)
removeAttribute(name)
getDocument()
getParent()
isInline()
isBlock()
isRole(expectedValue)
getRole()
setRole(names)
hasRole(name)
getRoles()
addRole(name)
removeRole(name)
isReftext()
getReftext()
getContext()
getId()
setId(id)
isOption(name)
setOption(name)
getIconUri(name)
getMediaUri(target, assetDirKey)
getImageUri(targetImage, assetDirKey)
getConverter()
readContents(target, options)
readAsset(path, options)
normalizeWebPath(target, start, preserveTargetUri)
normalizeSystemPath(target, start, jail, options)
normalizeAssetPath(assetRef, assetName, autoCorrect)
createLogMessage
Instance Members
resolveBlockSubstitutions(subs, defaults, subject)
resolvePassSubstitutions(subs)

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.

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

 const source = '= Document Title'
 const 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.

Document

Extends AbstractBlock

Static Members
getRefs()
getImages()
hasFootnotes()
getFootnotes()
getHeader()
setAttribute(name, value)
removeAttribute(name)
convert(options?)
write(output, target)
getAuthor()
getSourceLines()
hasExtensions()
getDoctype()
getBackend()
isBasebackend(base)
getTitle()
setTitle(title)
getDocumentTitle(options)
getCatalog()
getReferences
getRevisionDate()
getRevdate()
getRevisionNumber()
getRevisionRemark()
setHeaderAttribute(name, value, overwrite)
getAuthors()
hasRevisionInfo()
getNoheader()
getNofooter()
playbackAttributes(blockAttributes)
deleteAttribute(name)
isAttributeLocked(key)
restoreAttributes()
parse(data?)
getDocinfo(docinfoLocation, suffix)
hasDocinfoProcessors(docinfoLocation?)
incrementAndStoreCounter(counterName, block)
counterIncrement
counter(name, seed)
getSafe()
getCompatMode()
getSourcemap()
setSourcemap(value)
getCounters()
getCallouts()
getBaseDir()
getOptions()
getOutfilesuffix()
getParentDocument()
getReader()
getConverter()
getExtensions()
Document/Footnote
Static Members
getIndex()
getId()
getText()
Document/ImageReference
Static Members
getTarget()
getImagesDirectory()

The Author class represents information about an author extracted from document attributes.

Document/Author
Static Members
getName()
getFirstName()
getMiddleName()
getLastName()
getInitials()
getEmail()
Document/RevisionInfo
Static Members
getDate()
getNumber()
getRemark()
isEmpty()
SafeMode
Static Members
getValueForName(name)
getNameForValue(value)
getNames()

Maintains a catalog of callouts and their associations.

Callouts
Static Members
create()
register(ordinal)
readNextId()
getCalloutIds(ordinal)
getListIndex()
getCurrentList()
nextList()
rewind()

A partitioned title (i.e., title & subtitle).

Document/Title
Static Members

Methods for managing inline elements in AsciiDoc block.

Inline

Extends AbstractNode

Static Members
create(parent, context, text, opts)
convert()
getText()
getType()
getTarget()
getAlt()

Methods for managing AsciiDoc lists (ordered, unordered and description lists).

List

Extends AbstractBlock

Static Members
hasItems()
getItems()

Methods for managing items for AsciiDoc olists, ulist, and dlists.

In a description list (dlist), each item is a tuple that consists of a 2-item Array of ListItem terms and a ListItem description (i.e., [[term, term, ...], desc]. If a description is not set, then the second entry in the tuple is nil.

ListItem

Extends AbstractBlock

Static Members
getText()
setText(text)
hasText()
getMarker()
setMarker(marker)
getList()
Reader
Static Members
pushInclude(data, file, path, lineno, attributes)
getCursor()
getLines()
getString()
hasMoreLines()
isEmpty()
peekLine(direct)
readLine()
readLines()
read()
advance()
createLogMessage
Cursor
Static Members
getFile()
getDirectory()
getPath()
getLineNumber()
LoggerManager
Static Members
setLogger(logger)
newLogger(name, functions)
newFormatter(name, functions)
LoggerSeverity
Static Members
get(severity)
LoggerFormatter
Static Members
call(severity, time, programName, message)
MemoryLogger
Static Members
create()
getMessages()
Logger
Static Members
getMaxSeverity()
getFormatter()
setFormatter(formatter)
getLevel()
setLevel(level)
getProgramName()
setProgramName(programName)
NullLogger
Static Members
create()
getMaxSeverity()
Timings
Static Members
create()
printReport(to?, subject?)

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.

SyntaxHighlighter
Static Members
register(names, functions)
get(name)
for
SyntaxHighlighterBase
Static Members
registerFor(names)

Methods for managing AsciiDoc tables.

Table

Extends AbstractBlock

Static Members
create(parent, attributes)
getCaption()
getRows()
getColumns()
getHeadRows()
hasHeadRows()
getBodyRows()
getFootRows()
hasHeaderOption()
hasFooterOption()
hasAutowidthOption()
getRowCount()
setRowCount(value)
getColumnCount()
setColumnCount(value)
Instance Members
hasBodyRows()
hasFootRows()
Rows
Static Members
create(head, foot, body)
Instance Members
getHead()
getFoot()
getBody()
bySection()

Methods to manage the columns of an AsciiDoc table. In particular, it keeps track of the column specs.

Column

Extends AbstractNode

Static Members
create(table, index, attributes)
getColumnNumber()
getWidth()
getHorizontalAlign()
getVerticalAlign()
getStyle()

Methods for managing the cells in an AsciiDoc table.

Cell

Extends AbstractBlock

Static Members
create(column, cellText, attributes, opts)
getColumnSpan()
setColumnSpan(value)
getRowSpan()
setRowSpan(value)
getContent()
getText()
getSource()
getLines()
getLineNumber()
getFile()
getStyle()
getColumn()
getWidth()
getColumnPercentageWidth()
getInnerDocument()

This API is experimental and subject to change.

Please note that this API is currently only available in a Node environment. We recommend to use a custom converter if you are running in the browser.

Converter/TemplateConverter
Static Members
create(backend, templateDirectories, opts)
getCache()
clearCache()
convert(node, templateName, opts)
handles(name)
getTemplates()
register(name, template)

This API is experimental and subject to change.

Please note that this API is currently only available in a Node environment. We recommend to use a custom converter if you are running in the browser.

A pluggable adapter for integrating a template engine into the built-in template converter.

TemplateEngine
Static Members
register(names, templateEngineAdapter)

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:

  1. After the source lines are normalized, {Extensions/Preprocessor}s modify or replace the source lines before parsing begins. {Extensions/IncludeProcessor}s are used to process include directives for targets which they claim to handle.
  2. The Parser parses the block-level content into an abstract syntax tree. Custom blocks and block macros are processed by associated {Extensions/BlockProcessor}s and {Extensions/BlockMacroProcessor}s, respectively.
  3. {Extensions/TreeProcessor}s are run on the abstract syntax tree.
  4. Conversion of the document begins, at which point inline markup is processed and converted. Custom inline macros are processed by associated {InlineMacroProcessor}s.
  5. {Extensions/Postprocessor}s modify or replace the converted document.
  6. The output is written to the output stream.

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.

Extensions
Example
asciidoctor.Extensions.register(function () {
  this.block(function () {
    const self = this
    self.named('shout')
    self.onContext('paragraph')
    self.process(function (parent, reader) {
      const lines = reader.getLines().map(function (l) { return l.toUpperCase(); })
      return self.createBlock(parent, 'paragraph', lines)
    })
  })
})
Static Members
create(name, block)
register(name, block)
getGroups()
unregisterAll()
unregister()
createPostprocessor(name, functions)
newPostprocessor(name, functions)
createPreprocessor(name, functions)
newPreprocessor(name, functions)
createTreeProcessor(name, functions)
newTreeProcessor(name, functions)
createIncludeProcessor(name, functions)
newIncludeProcessor(name, functions)
createDocinfoProcessor(name, functions)
newDocinfoProcessor(name, functions)
createBlockProcessor(name, functions)
newBlockProcessor(name, functions)
createInlineMacroProcessor(name, functions)
newInlineMacroProcessor(name, functions)
createBlockMacroProcessor(name, functions)
newBlockMacroProcessor(name, functions)
Extensions/Registry
Static Members
prefer(name, processor)
block(name, processor)
inlineMacro(name, processor)
includeProcessor(name, processor)
blockMacro(name, processor)
treeProcessor(name, processor)
postprocessor(name, processor)
preprocessor(name, processor)
docinfoProcessor(name, processor)
hasPreprocessors()
hasTreeProcessors()
hasIncludeProcessors()
hasPostprocessors()
hasDocinfoProcessors(location)
hasBlocks()
hasBlockMacros()
hasInlineMacros()
getPreprocessors()
getTreeProcessors()
getIncludeProcessors()
getPostprocessors()
getDocinfoProcessors(location)
getBlocks()
getBlockMacros()
getInlineMacros()
getInlineMacroFor(name)
getBlockFor(name, context)
getBlockMacroFor(name)
Extensions/Processor
Static Members
prepend()
process(block)
named(name)
createBlock(parent, context, source, attrs, opts)
createList(parent, context, attrs)
createListItem(parent, text)
createImageBlock(parent, attrs, opts)
createParagraph(parent, source, attrs, opts)
createOpenBlock(parent, source, attrs, opts)
createExampleBlock(parent, source, attrs, opts)
createPassBlock(parent, source, attrs, opts)
createListingBlock(parent, source, attrs, opts)
createLiteralBlock(parent, source, attrs, opts)
createAnchor(parent, text, opts)
createInlinePass(parent, text, opts)
createInline(parent, context, text, opts)
parseContent(parent, content, attrs)
parseAttributes(block, attrlist, opts)
positionalAttributes(value)
resolveAttributes(value?)
resolvesAttributes
getConfig()
option(key, value)
Extensions/BlockProcessor
Static Members
defaultAttributes(value)
onContext(context)
onContexts(contexts)
parseContentAs(value)
Extensions/BlockMacroProcessor
Static Members
defaultAttributes(value)
getName()
parseContentAs(value)
Extensions/InlineMacroProcessor
Static Members
defaultAttributes(value)
getName()
parseContentAs(value)
matchFormat(value)
match(value)
Extensions/IncludeProcessor
Static Members
handles(block)
Extensions/TreeProcessor
Static Members
Extensions/Postprocessor
Static Members
Extensions/Preprocessor
Static Members
Extensions/DocinfoProcessor
Static Members
atLocation(value)
Converter
Static Members
convert(node, transform, opts)
create(backend, opts)
Converter/Factory
Static Members
register(converter, backends)
getDefault(initialize)
create(backend, opts)
getRegistry()
for(backend)
Converter/Html5Converter
Static Members
create()
convert(node, transform?, opts?)