@asciidoctor/core 3.0.3 → 4.0.0-alpha.1

package/types/section.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Methods for managing sections of AsciiDoc content in a document.
+ */
+export class Section extends AbstractBlock<string> {
+    /**
+     * Create a new Section — mirrors the core Section.create() API.
+     * @param {AbstractBlock|null} [parent=null]
+     * @param {number|null} [level=null]
+     * @param {boolean} [numbered=false]
+     * @param {Object} [opts={}]
+     * @returns {Section}
+     */
+    static create(parent?: AbstractBlock | null, level?: number | null, numbered?: boolean, opts?: any): Section;
+    /**
+     * Generate a String ID from the given section title.
+     * @param {string} title - The String title.
+     * @param {object} document - The Document.
+     * @returns {string} the generated String ID.
+     */
+    static generateId(title: string, document: object): string;
+    /**
+     * Initialize an Asciidoctor Section object.
+     * @param {AbstractBlock|null} [parent=null] - The parent AbstractBlock (Document or Section), or null.
+     * @param {number|null} [level=null] - The Integer level of this section (default: parent.level + 1 or 1).
+     * @param {boolean} [numbered=false] - Boolean indicating whether numbering is enabled.
+     * @param {Object} [opts={}] - An optional plain object of options.
+     */
+    constructor(parent?: AbstractBlock | null, level?: number | null, numbered?: boolean, opts?: any);
+    special: boolean;
+    numbered: boolean;
+    index: number;
+    sectname: string;
+    /**
+     * The name of this section — alias for title.
+     * @returns {string|null}
+     */
+    get name(): string | null;
+    /**
+     * Generate a String ID from the title of this section.
+     * This sync convenience method is only called outside of parsing (e.g. extensions).
+     * At that point #convertedTitle is already set, so this.title returns the fully-substituted
+     * HTML title — matching Ruby's behaviour where section.title calls apply_title_subs.
+     * @returns {string}
+     */
+    generateId(): string;
+    /**
+     * Get the section number for the current Section as a dot-separated String.
+     * @param {string} [delimiter='.'] - The separator between numerals.
+     * @param {string|false|null} [append=null] - String appended at the end, or false to omit trailing delimiter
+     *   (default: null → same as delimiter).
+     * @returns {string} the section number String.
+     */
+    sectnum(delimiter?: string, append?: string | false | null): string;
+    /**
+     * Append a content block to this block's list of blocks.
+     * If the child block is a Section, assign an index/numeral to it.
+     * @param {AbstractBlock} block - The child Block to append.
+     * @returns {this}
+     */
+    append(block: AbstractBlock): this;
+    /**
+     * Get the section title (alias of title).
+     * @returns {string|null}
+     */
+    getName(): string | null;
+    /**
+     * Get the section name (e.g. 'section', 'appendix').
+     * @returns {string|null}
+     */
+    getSectionName(): string | null;
+    /**
+     * Set the section name (e.g. 'section', 'appendix').
+     * @param {string|null} val
+     */
+    setSectionName(val: string | null): void;
+    /**
+     * Get the 0-based index of this section within the parent block.
+     * @returns {number}
+     */
+    getIndex(): number;
+    /**
+     * Set the 0-based index of this section within the parent block.
+     * @param {number} val
+     */
+    setIndex(val: number): void;
+    /**
+     * Get whether this section is numbered.
+     * @returns {boolean}
+     */
+    isNumbered(): boolean;
+    /**
+     * Get whether this section is a special section.
+     * @returns {boolean}
+     */
+    isSpecial(): boolean;
+    /**
+     * Set whether this section is a special section.
+     * @param {boolean} val
+     */
+    setSpecial(val: boolean): void;
+    /**
+     * Get the section numeral string.
+     * @returns {string|null}
+     */
+    getNumeral(): string | null;
+    /**
+     * Set the section numeral string.
+     * @param {string|null} val
+     */
+    setNumeral(val: string | null): void;
+    /**
+     * Get the section number string (dot-separated).
+     * @returns {string}
+     */
+    getSectionNumeral(): string;
+    /**
+     * Get the section number string (alias of getSectionNumeral).
+     * @returns {string}
+     */
+    getSectionNumber(): string;
+}
+import { AbstractBlock } from './abstract_block.js';

package/types/stylesheets.d.ts

@@ -0,0 +1,10 @@
+export namespace Stylesheets {
+    let instance: StylesheetsClass;
+}
+declare class StylesheetsClass {
+    static DEFAULT_STYLESHEET_NAME: string;
+    get primaryStylesheetName(): string;
+    primaryStylesheetData(): Promise<string>;
+    embedPrimaryStylesheet(): Promise<string>;
+}
+export {};

package/types/substitutors.d.ts

@@ -0,0 +1,208 @@
+export namespace Substitutors {
+    /**
+     * Apply the specified substitutions to the text.
+     *
+     * @param {string|string[]} text - The text to process; must not be null.
+     * @param {string[]} [subs=NORMAL_SUBS] - The substitutions to perform.
+     * @returns {string|string[]} Text with substitutions applied.
+     */
+    function applySubs(text: string | string[], subs?: string[]): string | string[];
+    /** Apply normal substitutions (alias for applySubs with default args). */
+    function applyNormalSubs(text: any): Promise<string | string[]>;
+    /** Apply substitutions for header metadata and attribute assignments.
+     * Header subs are 'specialcharacters' + 'attributes', both of which are
+     * purely synchronous operations — so this method is intentionally sync
+     * to allow it to be called from synchronous contexts such as setAttribute()
+     * and the {set:...} directive inside subAttributes(). */
+    function applyHeaderSubs(text: any): string;
+    /** Apply substitutions for titles (alias for applySubs). */
+    function applyTitleSubs(text: any, subs?: readonly string[]): Promise<string | string[]>;
+    /** Apply substitutions for reftext. */
+    function applyReftextSubs(text: any): Promise<string | string[]>;
+    /**
+     * Substitute special characters (encode XML entities).
+     *
+     * @param {string} text
+     * @returns {string}
+     */
+    function subSpecialchars(text: string): string;
+    /** Alias for subSpecialchars. */
+    function subSpecialcharacters(text: any): string;
+    /**
+     * Substitute quoted text (emphasis, strong, monospaced, etc.)
+     *
+     * @param {string} text
+     * @returns {string}
+     */
+    function subQuotes(text: string): string;
+    /**
+     * Substitute attribute references in the specified text.
+     *
+     * @param {string} text
+     * @param {Object} [opts={}]
+     * @returns {string}
+     */
+    function subAttributes(text: string, opts?: any): string;
+    /**
+     * Substitute replacement characters (copyright, trademark, etc.)
+     *
+     * @param {string} text
+     * @returns {string}
+     */
+    function subReplacements(text: string): string;
+    /**
+     * Substitute inline macros (links, images, etc.)
+     *
+     * @param {string} text
+     * @returns {string}
+     */
+    function subMacros(text: string): string;
+    /**
+     * Substitute post replacements (hard line breaks).
+     *
+     * @param {string} text
+     * @returns {string}
+     */
+    function subPostReplacements(text: string): string;
+    /**
+     * Apply verbatim substitutions on source.
+     *
+     * @param {string} source
+     * @param {boolean} processCallouts
+     * @returns {string}
+     */
+    function subSource(source: string, processCallouts: boolean): string;
+    /**
+     * Substitute callout source references.
+     *
+     * @param {string} text
+     * @returns {string}
+     */
+    function subCallouts(text: string): string;
+    /**
+     * Highlight (colorize) the source code using a syntax highlighter.
+     *
+     * @param {string} source
+     * @param {boolean} processCallouts
+     * @returns {string}
+     */
+    function highlightSource(source: string, processCallouts: boolean): string;
+    /**
+     * Resolve line numbers to highlight from a test string.
+     *
+     * @param {string} source
+     * @param {string} spec   - e.g. "1-5, !2, 10" or "1..5;!2;10"
+     * @param {number|null} [start=null]
+     * @returns {number[]}
+     */
+    function resolveLinesToHighlight(source: string, spec: string, start?: number | null): number[];
+    /**
+     * Extract passthrough text for reinsertion after processing.
+     *
+     * @param {string} text
+     * @returns {string} Text with passthrough regions replaced by placeholders.
+     */
+    function extractPassthroughs(text: string): string;
+    /**
+     * Restore passthrough text by reinserting into placeholder positions.
+     *
+     * @param {string} text
+     * @returns {string}
+     */
+    function restorePassthroughs(text: string): string;
+    /**
+     * Resolve the list of comma-delimited subs against the possible options.
+     *
+     * @param {string} subs
+     * @param {'block'|'inline'} [type='block']
+     * @param {string[]|null} [defaults=null]
+     * @param {string|null} [subject=null]
+     * @returns {string[]|undefined}
+     */
+    function resolveSubs(subs: string, type?: "block" | "inline", defaults?: string[] | null, subject?: string | null): string[] | undefined;
+    /** Call resolveSubs for the 'block' type. */
+    function resolveBlockSubs(subs: any, defaults: any, subject: any): string[];
+    /** Call resolveSubs for the 'inline' type with subject set as passthrough macro. */
+    function resolvePassSubs(subs: any, subject?: string): string[];
+    /**
+     * Expand all groups in the subs list and return.
+     *
+     * @param {string|string[]} subs
+     * @param {string|null} [subject=null]
+     * @returns {string[]|null}
+     */
+    function expandSubs(subs: string | string[], subject?: string | null): string[] | null;
+    /**
+     * Commit the requested substitutions to this block.
+     * Looks for an attribute named "subs". If present, resolves substitutions.
+     */
+    function commitSubs(): any;
+    /**
+     * Parse attributes in name or name=value format from a comma-separated String.
+     *
+     * @param {string} attrlist
+     * @param {string[]} [posattrs=[]]
+     * @param {Object} [opts={}]
+     * @returns {Object}
+     */
+    function parseAttributes(attrlist: string, posattrs?: string[], opts?: any): any;
+    function extractAttributesFromText(text: any, defaultText?: any): Promise<any[]>;
+    function extractCallouts(source: any): any[];
+    function restoreCallouts(source: any, calloutMarks: any, sourceOffset?: any): Promise<string>;
+    function convertQuotedText(args: any, type: any, scope: any): Promise<any>;
+    function doReplacement(match: any, replacement: any, restore: any): any;
+    /** Inserts text into a formatted text enclosure (sprintf). */
+    function subPlaceholder(format: any, ...args: any[]): any;
+    function parseQuotedTextAttributes(str: any): {};
+    function normalizeText(text: any, normalizeWhitespace?: any, unescapeClosingSquareBrackets?: any): any;
+    function splitSimpleCsv(str: any): any;
+}
+import { BASIC_SUBS } from './constants.js';
+export const HEADER_SUBS: readonly string[];
+export const NO_SUBS: readonly any[];
+import { NORMAL_SUBS } from './constants.js';
+export const REFTEXT_SUBS: readonly string[];
+export const VERBATIM_SUBS: readonly string[];
+export namespace SUB_GROUPS {
+    export { NO_SUBS as none };
+    export { NORMAL_SUBS as normal };
+    export { VERBATIM_SUBS as verbatim };
+    export { BASIC_SUBS as specialchars };
+}
+export namespace SUB_HINTS {
+    let a: string;
+    let m: string;
+    let n: string;
+    let p: string;
+    let q: string;
+    let r: string;
+    let c: string;
+    let v: string;
+}
+export namespace SUB_OPTIONS {
+    let block: string[];
+    let inline: string[];
+}
+export const CAN: "\u0018";
+export const DEL: "";
+export const PASS_START: "\u0096";
+export const PASS_END: "\u0097";
+export const PASS_SLOT_RX: RegExp;
+export const HIGHLIGHTED_PASS_SLOT_RX: RegExp;
+export const RS: "\\";
+export const R_SB: "]";
+export const ESC_R_SB: "\\]";
+export const PLUS: "+";
+export const SPECIAL_CHARS_RX: RegExp;
+export const SPECIAL_CHARS_TR: {
+    '>': string;
+    '<': string;
+    '&': string;
+};
+export namespace QUOTED_TEXT_SNIFF_RX {
+    let _false: RegExp;
+    export { _false as false };
+    let _true: RegExp;
+    export { _true as true };
+}
+export { BASIC_SUBS, NORMAL_SUBS };

package/types/syntaxHighlighter/highlightjs.d.ts

@@ -0,0 +1,33 @@
+export class HighlightJsAdapter extends SyntaxHighlighterBase {
+    constructor(...args: any[]);
+    /**
+     * Wrap the source block in `<pre><code>` with highlight.js CSS classes.
+     *
+     * Adds `language-<lang>` and `hljs` to the `<code>` class attribute, and strips
+     * the `highlight` class from `<pre>` when the `nohighlight-option` attribute is set.
+     * @param {object} node - the source Block being processed
+     * @param {string|null} lang - the source language string, or falsy if none
+     * @param {object} opts - options passed to the base format()
+     * @returns {Promise<string>}
+     */
+    format(node: object, lang: string | null, opts: object): Promise<string>;
+    /**
+     * Always returns true — highlight.js injects markup into the document.
+     * @param {string} location - 'head' or 'footer'
+     * @returns {true}
+     */
+    hasDocinfo(location: string): true;
+    /**
+     * Returns the CSS `<link>` tag (head) or the `<script>` tags (footer).
+     * @param {string} location - 'head' or 'footer'
+     * @param {object} doc - the Document being converted
+     * @param {{ cdn_base_url: string, self_closing_tag_slash: string }} opts
+     * @returns {string}
+     */
+    docinfo(location: string, doc: object, opts: {
+        cdn_base_url: string;
+        self_closing_tag_slash: string;
+    }): string;
+}
+export default HighlightJsAdapter;
+import { SyntaxHighlighterBase } from '../syntax_highlighter.js';

package/types/syntaxHighlighter/html_pipeline.d.ts

@@ -0,0 +1,16 @@
+export class HtmlPipelineAdapter extends SyntaxHighlighterBase {
+    constructor(...args: any[]);
+    /**
+     * Wrap the source block in `<pre><code>` without highlight classes.
+     *
+     * The html-pipeline gem processes the markup downstream, so only a bare
+     * `<pre lang="<lang>"><code>` wrapper is emitted (no CSS classes, no data-lang).
+     * @param {object} node - the source Block being processed
+     * @param {string|null} lang - the source language string, or falsy if none
+     * @param {object} opts - options (unused by this adapter)
+     * @returns {Promise<string>} the wrapped source string
+     */
+    format(node: object, lang: string | null, opts: object): Promise<string>;
+}
+export default HtmlPipelineAdapter;
+import { SyntaxHighlighterBase } from '../syntax_highlighter.js';

package/types/syntax_highlighter.d.ts

@@ -0,0 +1,167 @@
+/** @import { Block } from './block.js' */
+/**
+ * Base class for syntax highlighter adapters.
+ *
+ * Subclasses should override the methods they need. Two usage patterns:
+ * 1. Server-side highlighting: override `handlesHighlighting()` → true and `highlight()`.
+ * 2. Client-side highlighting: override `hasDocinfo()` → true and `docinfo()`.
+ *
+ * Both patterns may also override `format()`.
+ */
+export class SyntaxHighlighterBase {
+    /**
+     * @param {string} name - the name identifying this adapter
+     * @param {string} [backend='html5'] - the backend name
+     * @param {Object} [opts={}] - options
+     */
+    constructor(name: string, backend?: string, opts?: any);
+    name: string;
+    _preClass: string;
+    /**
+     * Indicates whether this highlighter has docinfo markup to insert at the specified location.
+     *
+     * @param {string} location - the location slot ('head' or 'footer')
+     * @returns {boolean} false by default; subclasses return true to enable {@link docinfo}
+     */
+    hasDocinfo(location: string): boolean;
+    /**
+     * Generates docinfo markup to insert at the specified location in the output document.
+     *
+     * @param {string} location - the location slot ('head' or 'footer')
+     * @param {Document} doc - the Document in which this highlighter is used
+     * @param {Object} opts - options
+     * @param {boolean} [opts.linkcss] - link stylesheet instead of embedding
+     * @param {string} [opts.cdn_base_url] - base URL for CDN assets
+     * @param {string} [opts.self_closing_tag_slash] - '/' for self-closing tags
+     * @returns {string} the markup to insert
+     */
+    docinfo(location: string, doc: Document, opts: {
+        linkcss?: boolean;
+        cdn_base_url?: string;
+        self_closing_tag_slash?: string;
+    }): string;
+    /**
+     * Indicates whether highlighting is handled server-side by this highlighter.
+     *
+     * @returns {boolean} false by default; subclasses return true to enable {@link highlight}
+     */
+    handlesHighlighting(): boolean;
+    /**
+     * Highlights the specified source when this source block is being converted.
+     *
+     * If the source contains callout marks, the caller assumes the source remains on the same
+     * lines and no closing tags are added to the end of each line. If the source gets shifted
+     * by one or more lines, return a tuple of the highlighted source and the line offset.
+     *
+     * @param {Block} node - the source Block to highlight
+     * @param {string} source - the raw source text
+     * @param {string} lang - the source language (e.g. 'ruby')
+     * @param {Object} opts - options
+     * @param {Object} [opts.callouts] - callouts indexed by line number
+     * @param {string} [opts.css_mode] - CSS mode ('class' or 'inline')
+     * @param {number[]} [opts.highlight_lines] - 1-based line numbers to emphasize
+     * @param {string} [opts.number_lines] - 'table' or 'inline' if lines should be numbered
+     * @param {number} [opts.start_line_number] - starting line number (default: 1)
+     * @param {string} [opts.style] - theme name
+     * @returns {string|[string, number]} the highlighted source, or a tuple with a line offset
+     */
+    highlight(node: Block, source: string, lang: string, opts: {
+        callouts?: any;
+        css_mode?: string;
+        highlight_lines?: number[];
+        number_lines?: string;
+        start_line_number?: number;
+        style?: string;
+    }): string | [string, number];
+    /**
+     * Formats the highlighted source for inclusion in an HTML document.
+     *
+     * @param {Block} node - the source Block being processed
+     * @param {string} lang - the source language (e.g. 'ruby')
+     * @param {Object} opts - options
+     * @param {boolean} [opts.nowrap] - disable line wrapping
+     * @param {Function} [opts.transform] - called with (pre, code) attribute objects before building tags
+     * @returns {Promise<string>|string} the highlighted source wrapped in &lt;pre&gt;&lt;code&gt; tags.
+     *   Subclasses may return a plain `string` — the caller always `await`s the result.
+     */
+    format(node: Block, lang: string, opts: {
+        nowrap?: boolean;
+        transform?: Function;
+    }): Promise<string> | string;
+    /**
+     * Indicates whether this highlighter wants to write a stylesheet to disk.
+     *
+     * @param {Document} doc - the Document in which this highlighter is being used
+     * @returns {boolean} false by default; subclasses return true to enable {@link writeStylesheetToDisk}
+     */
+    writeStylesheet(doc: Document): boolean;
+    /**
+     * Writes the stylesheet to disk.
+     *
+     * @param {Document} doc - the Document in which this highlighter is used
+     * @param {string} toDir - the absolute path of the output directory
+     */
+    writeStylesheetToDisk(doc: Document, toDir: string): void;
+}
+/**
+ * A syntax highlighter factory backed by a caller-supplied registry.
+ */
+export class CustomFactory {
+    /**
+     * @param {Object|null} [seedRegistry=null] - initial registry entries
+     */
+    constructor(seedRegistry?: any | null);
+    _registry: any;
+    /**
+     * Associates a syntax highlighter class or instance with one or more names.
+     *
+     * @param {Function|SyntaxHighlighterBase} syntaxHighlighter - the class or instance to register
+     * @param {...string} names - one or more names to associate
+     */
+    register(syntaxHighlighter: Function | SyntaxHighlighterBase, ...names: string[]): void;
+    /**
+     * Retrieves the syntax highlighter class or instance registered for the given name.
+     *
+     * @param {string} name - the name to look up
+     * @returns {Function|SyntaxHighlighterBase|null} the registered class or instance, or null
+     */
+    for(name: string): Function | SyntaxHighlighterBase | null;
+    /**
+     * Resolves a name to a syntax highlighter instance.
+     *
+     * @param {string} name - the name of the syntax highlighter
+     * @param {string} [backend='html5'] - the backend name
+     * @param {Object} [opts={}] - options passed to the constructor
+     * @returns {SyntaxHighlighterBase|null} a highlighter instance, or null if not registered
+     */
+    create(name: string, backend?: string, opts?: any): SyntaxHighlighterBase | null;
+}
+export class DefaultFactoryProxy extends CustomFactory {
+    /**
+     * @param {Object} overrides - map of name → class/instance/null
+     * @param {CustomFactory} fallback - factory to delegate to when name is not overridden
+     */
+    constructor(overrides: any, fallback: CustomFactory);
+    _fallback: CustomFactory;
+    for(name: any): any;
+}
+export class DefaultFactory extends CustomFactory {
+    constructor();
+    _defaultRegistry: {};
+    register(syntaxHighlighter: any, ...names: any[]): void;
+    for(name: any): any;
+    /**
+     * Retrieves the syntax highlighter class or instance registered for the given name.
+     *
+     * @param {string} name - the name of the syntax highlighter to retrieve
+     * @returns {Function|SyntaxHighlighterBase|undefined} the registered class or instance, or undefined
+     */
+    get(name: string): Function | SyntaxHighlighterBase | undefined;
+    create(name: any, backend?: string, opts?: {}): any;
+    /**
+     * Clears all custom (user) registrations; built-in adapters are preserved.
+     */
+    unregisterAll(): void;
+}
+export const SyntaxHighlighter: DefaultFactory;
+import type { Block } from './block.js';