asciidoctor 4.0.0-alpha.6 → 4.0.0

package/lib/cli.js

@@ -126,6 +126,13 @@ const BASE_OPTION_DEFINITIONS = {
       'require the specified library before executing the processor (repeatable)',
     metavar: '<library>',
   },
+  extension: {
+    type: 'string',
+    multiple: true,
+    describe:
+      'require the specified extension and register it before executing the processor (repeatable)',
+    metavar: '<extension>',
+  },
   version: {
     type: 'boolean',
     short: 'V',
@@ -351,6 +358,7 @@ export class Invoker {
     }
 
     this._prepareProcessor(values)
+    this._prepareExtensions(values)
     const { options, failureLevel } = this.options
 
     const logger = LoggerManager.getLogger()
@@ -443,9 +451,25 @@ CLI version ${pkg.version}`
     const requirePaths = values.require
     if (!requirePaths) return
     for (const requirePath of requirePaths) {
-      const lib = requireLibrary(requirePath)
-      if (lib && typeof lib.register === 'function') {
-        lib.register(Extensions)
+      requireLibrary(requirePath)
+    }
+  }
+
+  /** @internal */
+  _prepareExtensions(values) {
+    const extensionPaths = values.extension
+    if (!extensionPaths || extensionPaths.length === 0) return
+    const logger = LoggerManager.getLogger()
+    for (const extensionPath of extensionPaths) {
+      const lib = requireLibrary(extensionPath)
+      if (typeof lib?.register === 'function') {
+        Extensions.register(function () {
+          lib.register(this)
+        })
+      } else {
+        logger.warn(
+          `Extension '${extensionPath}' does not export a register function and will be ignored.`
+        )
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asciidoctor",
-  "version": "4.0.0-alpha.6",
+  "version": "4.0.0",
   "description": "A JavaScript AsciiDoc processor powered by Asciidoctor",
   "type": "module",
   "main": "index.js",
@@ -60,7 +60,7 @@
   },
   "homepage": "https://github.com/asciidoctor/asciidoctor.js",
   "dependencies": {
-    "@asciidoctor/core": "4.0.0-alpha.6"
+    "@asciidoctor/core": "4.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",

package/types/extensions.d.ts

@@ -38,7 +38,25 @@ export namespace SyntaxProcessorDsl {
     function resolvesAttributes(...args: any[]): void;
 }
 export namespace IncludeProcessorDsl {
-    function handles(...args: any[]): any;
+    /**
+     * @overload
+     * @param {(target: string) => boolean} fn - Predicate that receives only the include target.
+     * @returns {void}
+     */
+    function handles(fn: (target: string) => boolean): void;
+    /**
+     * @overload
+     * @param {(doc: Document, target: string) => boolean} fn - Predicate that receives the document and the include target.
+     * @returns {void}
+     */
+    function handles(fn: (doc: Document, target: string) => boolean): void;
+    /**
+     * @overload
+     * @param {Document} doc - The document being parsed.
+     * @param {string} target - The include target.
+     * @returns {boolean}
+     */
+    function handles(doc: Document, target: string): boolean;
 }
 export namespace DocinfoProcessorDsl {
     function atLocation(value: any): void;
@@ -486,14 +504,38 @@ export class ProcessorExtension extends Extension {
     processMethod: any;
 }
 /**
- * A Group registers one or more extensions with a Registry.
+ * A Group bundles one or more extension registrations that are re-executed on
+ * every document conversion, making the registry safe to reuse.
  *
- * Subclass Group and pass the subclass to Extensions.register(), or call
- * the static register() method directly.
+ * Subclass Group, override {@link Group#activate}, and either call
+ * {@link Group.register} to add it globally or pass the subclass to
+ * {@link Extensions.create} / {@link Extensions.register}.
+ *
+ * @example
+ * class MyGroup extends Group {
+ *   activate (registry) {
+ *     registry.preprocessor(MyPreprocessor)
+ *   }
+ * }
+ * MyGroup.register()
  */
 export class Group {
-    static register(name?: any): void;
-    activate(_registry: any): void;
+    /**
+     * Register this Group class globally under the given name.
+     *
+     * Equivalent to calling `Extensions.register(name, this)`.
+     *
+     * @param {string|null} [name] - Optional name for the group.
+     */
+    static register(name?: string | null): void;
+    /**
+     * Called by {@link Registry#activate} on every document conversion.
+     *
+     * Override this method to register extensions with the provided registry.
+     *
+     * @param {Registry} _registry - The registry to register extensions with.
+     */
+    activate(_registry: Registry): void;
 }
 /**
  * The primary entry point into the extension system.
@@ -501,6 +543,18 @@ export class Group {
  * Registry holds the extensions which have been registered and activated, has
  * methods for registering or defining a processor and looks up extensions
  * stored in the registry during parsing.
+ *
+ * A registry can be reused across multiple conversions. Extensions registered
+ * via a group block (passed to {@link Extensions.create} or
+ * {@link Extensions.register}) are re-executed on every activation. Extensions
+ * registered directly on the registry instance (e.g. `registry.preprocessor(fn)`)
+ * are preserved across activations.
+ *
+ * @example
+ * const registry = Extensions.create('my-ext', function () {
+ *   this.preprocessor(function () { ... })
+ * })
+ * // registry can be passed to multiple conversions safely
  */
 export class Registry {
     constructor(groups?: {});
@@ -826,6 +880,13 @@ export namespace Extensions {
     /**
      * Create a new Registry, optionally pre-populated with a named block.
      *
+     * When a `block` is provided it is stored as a group and re-executed on every
+     * activation, making the registry safe to reuse across multiple conversions.
+     * Without a `block`, any extensions registered directly on the returned registry
+     * (e.g. `registry.preprocessor(fn)`) are stored in transient state that is
+     * cleared on every activation — those registrations will be lost from the second
+     * conversion onwards. Prefer the block form when the registry may be reused.
+     *
      * @param {string|null} [name=null] - Optional name for the group; auto-generated if omitted.
      * @param {Function|null} [block=null] - Optional function to register as the group.
      * @returns {Registry}
@@ -1032,6 +1093,7 @@ export type SyntaxProcessorDslInterface = ProcessorDslInterface & {
  * DSL interface for include processors.
  */
 export type IncludeProcessorDslInterface = DocumentProcessorDslInterface & {
+    handles(fn: (target: string) => boolean): void;
     handles(fn: (doc: Document, target: string) => boolean): void;
 };
 /**