v4.0.0-alpha.3

Summary

Release meta

Released on: 2026-05-20
Released by: github-actions[bot]
Published by: GitHub

Logs: full diff

Changelog

Documentation

• Add syntax highlighting guide explaining client-side (highlight.js via standalone + source-highlighter) and server-side (conversion-time) approaches, including the "embedding in an existing page" pattern
• Document how to run the test suite under Deno in CONTRIBUTING-CODE.adoc, including the installation prerequisite and the per-package commands
• Add customization overview page listing all extension levels from built-in attributes to custom converter
• Update stylesheets page to reflect that the stylesheet factory is deprecated and the default stylesheet no longer uses Sass

Improvements

• Export named TypeScript DSL interface types (ProcessorDslInterface, DocumentProcessorDslInterface, SyntaxProcessorDslInterface, IncludeProcessorDslInterface, DocinfoProcessorDslInterface, BlockProcessorDslInterface, MacroProcessorDslInterface, InlineMacroProcessorDslInterface) from @asciidoctor/core — TypeScript consumers can now use these as this context types in block-style extension registrations
• Type the process method precisely on each processor class: Preprocessor, TreeProcessor, Postprocessor, IncludeProcessor, DocinfoProcessor, BlockProcessor, MacroProcessor, BlockMacroProcessor, and InlineMacroProcessor now have fully typed parameter and return types instead of any
• Add Registry#getGroups() and Extensions#getGroups() as JavaScript-style accessor aliases for the groups property, following the dual accessor pattern
• Add missing JavaScript-style accessor aliases on Registry to match the previous Asciidoctor.js public API: blocks(), blockMacros(), getPreprocessors(), getTreeProcessors(), getIncludeProcessors(), getPostprocessors(), getDocinfoProcessors(), getBlocks(), getBlockMacros(), getInlineMacros(), getInlineMacroFor(), getBlockFor(), and getBlockMacroFor()
• Replace generic extension documentation examples with practical, real-world examples — block processor now demonstrates a callout block, include processor uses JSON data, inline macro renders npm badge links, postprocessor adds a copy button, tree processor computes reading time, block macro embeds GitHub Gists, and docinfo processor injects Open Graph metadata

Bug Fixes

• AbstractBlock#getAttributes() no longer exposes the internal attribute_entries bookkeeping key — attribute entries are now stored under a private Symbol key invisible to Object.keys(), for…in, and JSON.stringify()
• doc.doctitle() and doc.xreftext() now apply typographic substitutions (e.g., ' → ’) to the document title and reftext, matching the Ruby reference implementation
• NullLogger now properly extends Logger — instanceof Logger checks on a NullLogger instance now return true
• Strip UTF-8 BOM when it appears as three raw Latin-1 characters ( / \xEF\xBB\xBF) rather than the decoded U+FEFF codepoint — fixes loading of BOM-prefixed content passed through a binary/Latin-1 decoder
• load() now accepts a Uint8Array (including browser shim instances returned by Buffer.concat) in addition to Node.js Buffer — fixes "unsupported input type: object" error in browser environments
• TemplateConverter now sorts directory entries from readdir before scanning — ensures consistent template precedence when multiple engines provide the same node template (previously, a non-deterministic readdir order could pick Handlebars over Nunjucks depending on the runtime)

Infrastructure

• Add Deno compatibility shim for node:test (via deno.json import map): redirects node:test to a @std/testing/bdd-backed shim that provides working beforeEach/afterEach hooks — the full packages/core test suite now runs under Deno with 0 failures
• Replace shared LoggerManager mutation in tests with AsyncLocalStorage-based isolation via withLogger() — eliminates race conditions when tests run concurrently under Deno
• Add test-deno job to the CI workflow, gating native_images on both Node.js and Deno test results