Migration guide: @asciidoctor/core v3 → v4

@asciidoctor/core v4 is a complete rewrite of the library. v3 relied on Opal (a Ruby-to-JavaScript transpiler) to produce a JS bundle from the Ruby source. v4 is a native JavaScript implementation — no transpilation, no Ruby, pure ESM.

The library source is written in ESM only. For compatibility, a CommonJS bundle is also provided and the package.json exports field points to the appropriate format automatically — require() continues to work.

Requirements

  • Node.js >= 22 (LTS)

Breaking changes

Asynchronous API

All parsing and conversion operations now return a Promise and must be awaited.

v3 (Opal) v4 (native) Note

asciidoctor.load(source, opts) → Document

load(source, opts) → Promise<Document>

Must be awaited

asciidoctor.loadFile(path, opts) → Document

loadFile(path, opts) → Promise<Document>

Must be awaited

asciidoctor.convert(source, opts) → string

convert(source, opts) → Promise<string>

Must be awaited

asciidoctor.convertFile(path, opts) → string

convertFile(path, opts) → Promise<string>

Must be awaited

document.parse(data?) → Document

document.parse(data?) → Promise<Document>

Must be awaited

document.convert(opts?) → string

document.convert(opts?) → Promise<string>

Must be awaited

No factory call

v3 exports a factory function that must be called to obtain an Asciidoctor instance. v4 uses named exports — import only what you need, no factory call needed.

v3 v4

require('@asciidoctor/core')() → must call the factory

import { load, convert } from '@asciidoctor/core' → use functions directly

Strict camelCase naming

Some internal properties and options that retained the Ruby snake_case style in v3 are now camelCase.

v3 (snake_case) v4 (camelCase)

node_name

nodeName

source_location

sourceLocation

content_model

contentModel

default_subs

defaultSubs

Renamed methods

v3 v4 Note

isRole(expectedValue?) → boolean

hasRoleAttribute(expectedValue?) → boolean

Checks whether the role attribute is set

isOption(name) → boolean

hasOption(name) → boolean

Checks whether the <name>-option attribute is set

isReftext() → boolean

hasReftext() → boolean

Checks whether the reftext attribute is set. Note: v4 also retains isReftext() with broader semantics (returns true when reftext is set or the node has a title).

getAttr(name, defaultValue?, inherit?) → *

getAttribute(name, defaultValue?, inherit?) → *

getAttr is removed. Use getAttribute instead — the signature is identical.

getAttribute returns null instead of undefined

In v3, getAttribute(name) returned undefined when the attribute was absent. In v4, it returns null.

v3 v4

node.getAttribute('missing') === undefined → true

node.getAttribute('missing') === null → true

Update any code that checks the return value against undefined:

// v3
if (node.getAttribute('language') === undefined) { ... }

// v4
if (node.getAttribute('language') === null) { ... }
// or equivalently
if (!node.getAttribute('language')) { ... }

Restructured inner classes

v3 v4 Note

Document.Title (inner class)

DocumentTitle (named export)

Renamed to avoid collision with Document

Document.Author (inner class)

Author (named export)

Top-level export

Document.Footnote (inner class)

Footnote (named export)

Top-level export

Document.ImageReference (inner class)

ImageReference (named export)

Top-level export

Asynchronous methods on AbstractNode

v3 v4

getIconUri(name) → string

getIconUri(name) → Promise<string>

getImageUri(target, key?) → string

getImageUri(target, key?) → Promise<string>

readAsset(path, opts) → string | undefined

readAsset(path, opts) → Promise<string | null>

readContents(target, opts) → void

readContents(target, opts) → Promise<string | null>

Asynchronous methods on AbstractBlock

v3 v4

convert() → string

convert() → Promise<string>

getContent() → string

getContent() → Promise<string>

xreftext(xrefstyle?) → string|null

xreftext(xrefstyle?) → Promise<string|null>
alias: getXrefText(xrefstyle?)

Extensions transpiled with Opal

Extensions written in Ruby and transpiled to JavaScript via Opal will no longer work. v4 does not include the Opal runtime, so any Opal-generated code will fail at load time.

Extensions must be rewritten in pure JavaScript (ESM). The extension API is largely similar, but some differences may exist — refer to the extension documentation for details.

In addition, extension processors can now be asynchronous: the process method may return a Promise, which will be properly awaited during conversion.

v3 v4

Extensions written in Ruby, transpiled via Opal

Extensions written in pure JavaScript (ESM)

Custom converters

In v4, node.getContent() returns a Promise, so any converter that calls it must await the result. The convert() method itself can remain synchronous if it does not call getContent() or any other async API.

// v4 — synchronous converter (no async content call)
convert(node, transform) {
  return node.getTitle()
}

// v4 — async converter when getContent() is needed
async convert(node, transform) {
  return `<p>${await node.getContent()}</p>`
}

Custom syntax highlighters

The syntax highlighter API distinguishes between two methods with different async requirements:

  • highlight(node, source, lang, opts) — must remain synchronous, returns a string or [string, number]

  • format(node, lang, opts) — can be synchronous or asynchronous; returning a Promise<string> is recommended for I/O-bound operations, but a plain string works too

CLI: --require no longer registers extensions

This change applies to the asciidoctor CLI package.

In v3, --require (-r) loaded the given module and automatically called its exported register function, so it was the way to load extensions from the command line. In v4, these two concerns are separate options:

  • --require <library> (-r) — loads the module for its side effects only, without calling any exported function. Use it for libraries that configure themselves on load (syntax highlighters, polyfills, etc.) or for extensions that self-register at the top level via Extensions.register().

  • --extension <extension> — loads the module and calls its register(registry) named export with a shared registry. Repeat the option to load multiple extensions.

For example, to load the asciidoctor-kroki extension:

$ asciidoctor -r asciidoctor-kroki doc.adoc (1)
$ asciidoctor --extension asciidoctor-kroki doc.adoc (2)
1 v3
2 v4

Not implemented in v4

Feature Note

Asciidoctor.getRuntime() → Object

Returns platform / engine / GEM_HOME info; no equivalent concept in a native JS library

New in v4

Named exports

v4 is named-exports only — there is no default export. Every public member is available as a named export.

Functions
import { load, convert, loadFile, convertFile, getVersion, getCoreVersion } from '@asciidoctor/core'
Document and AST nodes
import {
  Document,
  DocumentTitle,
  Author,
  Footnote,
  ImageReference,
  RevisionInfo,
  AbstractNode,
  AbstractBlock,
  Block,
  Section,
  Inline,
  List,
  ListItem,
} from '@asciidoctor/core'
Reader
import { Reader, Cursor } from '@asciidoctor/core'
Converters
import {
  ConverterFactory,
  DefaultConverterFactory,
  Html5Converter,
} from '@asciidoctor/core'
Extensions
import {
  Extensions,
  Registry,
  ProcessorExtension,
  Preprocessor,
  TreeProcessor,
  Postprocessor,
  IncludeProcessor,
  DocinfoProcessor,
  BlockProcessor,
  InlineMacroProcessor,
  BlockMacroProcessor,
} from '@asciidoctor/core'
Syntax highlighter
import {
  SyntaxHighlighter,
  SyntaxHighlighterBase,
  DefaultSyntaxHighlighterFactory,
} from '@asciidoctor/core'
Logging and utilities
import {
  Logger,
  LoggerManager,
  MemoryLogger,
  NullLogger,
  SafeMode,
  ContentModel,
  Timings,
} from '@asciidoctor/core'
loadFile and convertFile are not available as named exports in the browser build.

Document direct properties

The v3 getter methods are preserved unchanged. In addition, v4 exposes these values as direct instance properties for convenience.

Getter method (v3 and v4) Direct property (new in v4)

getSafe() → number

document.safe

getCompatMode() → boolean

document.compatMode

getSourcemap() / setSourcemap(v)

document.sourcemap

getBaseDir() → string

document.baseDir

getOutfilesuffix() → string

document.outfilesuffix

getBackend() → string

document.backend

getDoctype() → string

document.doctype