@d10f/asciidoc-astro-loader 0.0.1

package/dist/index-Cf7MF6tZ.d.cts

@@ -0,0 +1,325 @@
+import { HighlighterCore, CodeToHastOptions, CodeOptionsMultipleThemes, ThemeRegistrationAny, StringLiteralUnion, BundledTheme } from 'shiki';
+import { AbstractNode } from 'asciidoctor';
+import { z } from 'zod';
+
+type RequiredOptions = z.output<typeof loaderOptionsSchema>;
+type DocumentOptions = RequiredOptions['document'];
+type PreambleOptions = RequiredOptions['preamble'];
+declare const loaderOptionsSchema: z.ZodObject<{
+    base: z.ZodString;
+    document: z.ZodDefault<z.ZodObject<{
+        mode: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"safe">, z.ZodLiteral<"unsafe">]>>;
+        template: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string, string>>;
+        recursive: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$loose>>;
+    syntaxHighlighting: z.ZodDefault<z.ZodPipe<z.ZodObject<{
+        theme: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            light: z.ZodString;
+            dark: z.ZodString;
+        }, z.core.$catchall<z.ZodString>>]>, z.ZodTransform<{
+            light: string;
+            dark: string;
+        } & {
+            [other: string]: string;
+        }, string | {
+            [x: string]: string;
+            light: string;
+            dark: string;
+        }>>>;
+        defaultColor: z.ZodDefault<z.ZodString>;
+        cssVariablePrefix: z.ZodDefault<z.ZodString>;
+        mergeWhitespaces: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"never">]>>;
+        tabindex: z.ZodDefault<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodLiteral<false>]>>;
+    }, z.core.$strip>, z.ZodTransform<{
+        defaultColor: string;
+        cssVariablePrefix: string;
+        mergeWhitespaces: boolean | "never";
+        tabindex: string | number | false;
+        themes: {
+            light: string;
+            dark: string;
+        } & {
+            [other: string]: string;
+        };
+    }, {
+        theme: {
+            light: string;
+            dark: string;
+        } & {
+            [other: string]: string;
+        };
+        defaultColor: string;
+        cssVariablePrefix: string;
+        mergeWhitespaces: boolean | "never";
+        tabindex: string | number | false;
+    }>>>;
+    preamble: z.ZodDefault<z.ZodObject<{
+        tableOfContents: z.ZodDefault<z.ZodBoolean>;
+        maxLevel: z.ZodDefault<z.ZodNumber>;
+        position: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"before">, z.ZodLiteral<"after">]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+
+declare abstract class AbstractEngine {
+    private _name;
+    private _extensions;
+    protected templateList: Map<NodeContext, string>;
+    constructor(_name: string, _extensions: string[]);
+    /**
+     * Returns the given name to this template engine.
+     */
+    get name(): string;
+    /**
+     * Returns the list of extensions this template engine supports.
+     */
+    get extensions(): string[];
+    /**
+     * Accessor method to check if instance implements the
+     * TemplateModule interface.
+     */
+    get canLoad(): boolean;
+    /**
+     * Accessor method to check if instance implements the
+     * AsciidocTemplate interface.
+     */
+    get canRenderNode(): boolean;
+    /**
+     * Accessor method to check if instance implements the
+     * FilesystemTemplate interface.
+     */
+    get canRenderFile(): boolean;
+    /**
+     * Accessor method to check if instance implements the
+     * RawTemplate interface.
+     */
+    get canRenderString(): boolean;
+    /**
+     * Appends a new context that this template engine will act upon.
+     */
+    addContext(context: NodeContext, filepath: string): void;
+    /**
+     * Verifies whether the specified context is being tracked or not.
+     */
+    hasContext(context: NodeContext | AbstractNode): boolean;
+    /**
+     * Verifies if the specified file extension is supported
+     * by this template engine.
+     */
+    supportsExt(extension: string): boolean;
+}
+
+/**
+ * A custom template engine that works in-lieu of the default one, which
+ * doesn't seem to work when using custom converters.
+ */
+declare class TemplateEngineRegistry {
+    /**
+     * A list of supported templating engines, their associated extensions
+     * and associatied template files to render.
+     */
+    private static modules;
+    /**
+     * A list of all the node existing contexts an Asciidoc node can have.
+     */
+    private static nodeContexts;
+    constructor(templateEngines: Array<AbstractEngine & AsciidocTemplate>, options: TemplateEngineOptions);
+    /**
+     * Asynchronously loads the necessary third party modules.
+     */
+    loadEngines(): Promise<void>;
+    /**
+     * Returns the module with the given name.
+     */
+    getEngineByName(name: string): (AbstractEngine & AsciidocTemplate) | undefined;
+    /**
+     * Returns the module that supports the given extension.
+     */
+    getEngineByExtension(ext: string): (AbstractEngine & AsciidocTemplate) | undefined;
+    /**
+     * Converts the provided node using one of the registered template
+     * engine modules. For more granular control, gain access to the
+     * engine itself with _getEngineByName_ or _getEngineByExtension_
+     * and use one of its render methods directly.
+     */
+    convert(node: AbstractNode, options?: Record<string, unknown>): string | undefined;
+    /**
+     * Scans the templates directory and creates an index of all templates
+     * based on supported block names and extensions.
+     *
+     * @see https://docs.asciidoctor.org/asciidoctor.js/latest/extend/converter/template-converter/#naming-convention
+     */
+    private loadTemplates;
+}
+
+type CustomConverter = {
+    /**
+     * The node context, or node type, that this converter will act upon.
+     */
+    readonly nodeContext: NodeContext;
+    readonly nodeStyle?: string;
+    /**
+     * Path location to a template to be used for the current converter. When
+     * provided, it will take precedence over any default templates found.
+     */
+    template?: string;
+    /**
+     * Converts the given node.
+     *
+     * @param node the current node to convert
+     * @param templateEngine entrypoint to the template engine
+     * @returns an HTML string representing the node.
+     */
+    convert(node: AbstractNode, templateEngine?: TemplateEngineRegistry): string | null | undefined;
+};
+type CustomConverterFactoryFn<T extends object | undefined> = (converterOptions: T) => CustomConverterFn;
+type CustomConverterFn = (opts: RequiredOptions, highlighter: HighlighterCore) => CustomConverter;
+type AsciidocLoader = {
+    /**
+     * Path to the Asciidoc documents to parse.
+     */
+    base: string;
+    /**
+     * Options for the Asciidoctor parser.
+     */
+    document?: Partial<{
+        /**
+         * The mode of operation for Asciidoctor.
+         */
+        mode: DocumentOptions['mode'];
+        /**
+         * List of converters to use to parse the current document.
+         */
+        converters: CustomConverterFn[];
+        /**
+         * List of file system locations to templates to use when converting an
+         * Asciidoc document.
+         */
+        template: string;
+        /**
+         * Whether to search on sub-folders on the given template location
+         * for additional templates.
+         */
+        recursive: boolean;
+        /**
+         * List of custom template engines to use when producing the HTML5
+         * output for a given block. By default, *handlebars* and *nunjucks*
+         * are available.
+         *
+         * @default [new HandlebarsEngine(), new NunjucksEngine()]
+         */
+        templateEngines: Array<AbstractEngine & AsciidocTemplate>;
+    }>;
+    /**
+     * Options provided for the output of the preamble section, when
+     * there is one present in the parsed document.
+     */
+    preamble?: Partial<{
+        /**
+         * Whether to display the table of contents or not.
+         *
+         * @default true
+         */
+        tableOfContents: PreambleOptions['tableOfContents'];
+        /**
+         * How many levels of headings to include in the table of contents.
+         *
+         * @default 3
+         */
+        maxLevel: PreambleOptions['maxLevel'];
+        /**
+         * Whether to place the table of contents before or after the preamble, if
+         * there is one.
+         *
+         * @default "after"
+         */
+        position: PreambleOptions['position'];
+    }>;
+    /**
+     * Options for the Shiki highlighter.
+     */
+    syntaxHighlighting?: Partial<Pick<CodeToHastOptions, 'mergeWhitespaces' | 'tabindex'> & Pick<CodeOptionsMultipleThemes, 'cssVariablePrefix'> & {
+        /**
+         * The default theme applied to the code (via inline `color` style).
+         * The rest of the themes are applied via CSS variables, and toggled by CSS overrides.
+         *
+         * For example, if `defaultColor` is `light`, then `light` theme is applied to the code,
+         * and the `dark` theme and other custom themes are applied via CSS variables:
+         *
+         * ```html
+         * <span style="color:#{light};--shiki-dark:#{dark};--shiki-custom:#{custom};">code</span>
+         * ```
+         *
+         * When set to `false`, no default styles will be applied, and totally up to users to apply the styles:
+         *
+         * ```html
+         * <span style="--shiki-light:#{light};--shiki-dark:#{dark};--shiki-custom:#{custom};">code</span>
+         * ```
+         *
+         * When set to `light-dark()`, the default color will be rendered as `light-dark(#{light}, #{dark})`.
+         *
+         * ```html
+         * <span style="color:light-dark(#{light}, #{dark});--shiki-dark:#{dark};--shiki-custom:#{custom};">code</span>
+         * ```
+         *
+         * @default 'light-dark()'
+         */
+        defaultColor: Partial<Record<string, ThemeRegistrationAny | StringLiteralUnion<string>>>;
+        /**
+         * The syntax highlighter theme to use. It can be either a
+         * string that will apply for both light and dark mode by
+         * default (see defaultColor option), or an object with both
+         * "light" and "dark" properties. When passed as an object, it
+         * can have any arbitrary number of additional properties used
+         * to define custom themes.
+         *
+         * @default { light: 'catppuccin-latte', dark: 'catppuccin-macchiato' }
+         */
+        theme: BundledTheme | {
+            light: BundledTheme;
+            dark: BundledTheme;
+            [customTheme: string]: BundledTheme;
+        };
+    }>;
+};
+/**
+ * The types of context that an Asciidoc block can be.
+ */
+type NodeContext = 'admonition' | 'audio' | 'colist' | 'dlist' | 'document' | 'embedded' | 'example' | 'floating-title' | 'image' | 'inline_anchor' | 'inline_break' | 'inline_button' | 'inline_callout' | 'inline_footnote' | 'inline_image' | 'inline_indexterm' | 'inline_kbd' | 'inline_menu' | 'inline_quoted' | 'listing' | 'literal' | 'olist' | 'open' | 'outline' | 'page_break' | 'paragraph' | 'preamble' | 'quote' | 'section' | 'sidebar' | 'stem' | 'table' | 'thematic_break' | 'toc' | 'ulist' | 'verse' | 'video';
+type TemplateEngineOptions = {
+    rootDir: string;
+    recursive: boolean;
+};
+/**
+ * For engines that are modular and require third-party libraries like
+ * handlebars, nunjucks, etc.
+ */
+interface TemplateModule {
+    /**
+     * Loader function to import third-party modules asynchronously.
+     */
+    load(): Promise<void>;
+}
+/**
+ * Interface used by the default template engine, which can handle
+ * Asciidoctor.js' blocks directly. It should be the main entrypoint
+ * to the template rendering process.
+ */
+interface AsciidocTemplate {
+    renderNode(node: AbstractNode, options?: Record<string, unknown>): string;
+}
+/**
+ * Designates that the template will receive a file location that points
+ * to the template to render.
+ */
+interface FilesystemTemplate {
+    renderFile(filepath: string, options?: Record<string, unknown>): string;
+}
+/**
+ * Designates that the template will receive a string with the contents
+ * of the template, instead of a location to the template itself.
+ */
+interface RawTemplate {
+    renderString(content: string, options?: Record<string, unknown>): string;
+}
+
+export { type AsciidocLoader as A, type CustomConverterFactoryFn as C, type FilesystemTemplate as F, type NodeContext as N, type RawTemplate as R, type TemplateModule as T, type AsciidocTemplate as a, AbstractEngine as b };

package/dist/index-Cf7MF6tZ.d.ts

@@ -0,0 +1,325 @@
+import { HighlighterCore, CodeToHastOptions, CodeOptionsMultipleThemes, ThemeRegistrationAny, StringLiteralUnion, BundledTheme } from 'shiki';
+import { AbstractNode } from 'asciidoctor';
+import { z } from 'zod';
+
+type RequiredOptions = z.output<typeof loaderOptionsSchema>;
+type DocumentOptions = RequiredOptions['document'];
+type PreambleOptions = RequiredOptions['preamble'];
+declare const loaderOptionsSchema: z.ZodObject<{
+    base: z.ZodString;
+    document: z.ZodDefault<z.ZodObject<{
+        mode: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"safe">, z.ZodLiteral<"unsafe">]>>;
+        template: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string, string>>;
+        recursive: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$loose>>;
+    syntaxHighlighting: z.ZodDefault<z.ZodPipe<z.ZodObject<{
+        theme: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            light: z.ZodString;
+            dark: z.ZodString;
+        }, z.core.$catchall<z.ZodString>>]>, z.ZodTransform<{
+            light: string;
+            dark: string;
+        } & {
+            [other: string]: string;
+        }, string | {
+            [x: string]: string;
+            light: string;
+            dark: string;
+        }>>>;
+        defaultColor: z.ZodDefault<z.ZodString>;
+        cssVariablePrefix: z.ZodDefault<z.ZodString>;
+        mergeWhitespaces: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"never">]>>;
+        tabindex: z.ZodDefault<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodLiteral<false>]>>;
+    }, z.core.$strip>, z.ZodTransform<{
+        defaultColor: string;
+        cssVariablePrefix: string;
+        mergeWhitespaces: boolean | "never";
+        tabindex: string | number | false;
+        themes: {
+            light: string;
+            dark: string;
+        } & {
+            [other: string]: string;
+        };
+    }, {
+        theme: {
+            light: string;
+            dark: string;
+        } & {
+            [other: string]: string;
+        };
+        defaultColor: string;
+        cssVariablePrefix: string;
+        mergeWhitespaces: boolean | "never";
+        tabindex: string | number | false;
+    }>>>;
+    preamble: z.ZodDefault<z.ZodObject<{
+        tableOfContents: z.ZodDefault<z.ZodBoolean>;
+        maxLevel: z.ZodDefault<z.ZodNumber>;
+        position: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"before">, z.ZodLiteral<"after">]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+
+declare abstract class AbstractEngine {
+    private _name;
+    private _extensions;
+    protected templateList: Map<NodeContext, string>;
+    constructor(_name: string, _extensions: string[]);
+    /**
+     * Returns the given name to this template engine.
+     */
+    get name(): string;
+    /**
+     * Returns the list of extensions this template engine supports.
+     */
+    get extensions(): string[];
+    /**
+     * Accessor method to check if instance implements the
+     * TemplateModule interface.
+     */
+    get canLoad(): boolean;
+    /**
+     * Accessor method to check if instance implements the
+     * AsciidocTemplate interface.
+     */
+    get canRenderNode(): boolean;
+    /**
+     * Accessor method to check if instance implements the
+     * FilesystemTemplate interface.
+     */
+    get canRenderFile(): boolean;
+    /**
+     * Accessor method to check if instance implements the
+     * RawTemplate interface.
+     */
+    get canRenderString(): boolean;
+    /**
+     * Appends a new context that this template engine will act upon.
+     */
+    addContext(context: NodeContext, filepath: string): void;
+    /**
+     * Verifies whether the specified context is being tracked or not.
+     */
+    hasContext(context: NodeContext | AbstractNode): boolean;
+    /**
+     * Verifies if the specified file extension is supported
+     * by this template engine.
+     */
+    supportsExt(extension: string): boolean;
+}
+
+/**
+ * A custom template engine that works in-lieu of the default one, which
+ * doesn't seem to work when using custom converters.
+ */
+declare class TemplateEngineRegistry {
+    /**
+     * A list of supported templating engines, their associated extensions
+     * and associatied template files to render.
+     */
+    private static modules;
+    /**
+     * A list of all the node existing contexts an Asciidoc node can have.
+     */
+    private static nodeContexts;
+    constructor(templateEngines: Array<AbstractEngine & AsciidocTemplate>, options: TemplateEngineOptions);
+    /**
+     * Asynchronously loads the necessary third party modules.
+     */
+    loadEngines(): Promise<void>;
+    /**
+     * Returns the module with the given name.
+     */
+    getEngineByName(name: string): (AbstractEngine & AsciidocTemplate) | undefined;
+    /**
+     * Returns the module that supports the given extension.
+     */
+    getEngineByExtension(ext: string): (AbstractEngine & AsciidocTemplate) | undefined;
+    /**
+     * Converts the provided node using one of the registered template
+     * engine modules. For more granular control, gain access to the
+     * engine itself with _getEngineByName_ or _getEngineByExtension_
+     * and use one of its render methods directly.
+     */
+    convert(node: AbstractNode, options?: Record<string, unknown>): string | undefined;
+    /**
+     * Scans the templates directory and creates an index of all templates
+     * based on supported block names and extensions.
+     *
+     * @see https://docs.asciidoctor.org/asciidoctor.js/latest/extend/converter/template-converter/#naming-convention
+     */
+    private loadTemplates;
+}
+
+type CustomConverter = {
+    /**
+     * The node context, or node type, that this converter will act upon.
+     */
+    readonly nodeContext: NodeContext;
+    readonly nodeStyle?: string;
+    /**
+     * Path location to a template to be used for the current converter. When
+     * provided, it will take precedence over any default templates found.
+     */
+    template?: string;
+    /**
+     * Converts the given node.
+     *
+     * @param node the current node to convert
+     * @param templateEngine entrypoint to the template engine
+     * @returns an HTML string representing the node.
+     */
+    convert(node: AbstractNode, templateEngine?: TemplateEngineRegistry): string | null | undefined;
+};
+type CustomConverterFactoryFn<T extends object | undefined> = (converterOptions: T) => CustomConverterFn;
+type CustomConverterFn = (opts: RequiredOptions, highlighter: HighlighterCore) => CustomConverter;
+type AsciidocLoader = {
+    /**
+     * Path to the Asciidoc documents to parse.
+     */
+    base: string;
+    /**
+     * Options for the Asciidoctor parser.
+     */
+    document?: Partial<{
+        /**
+         * The mode of operation for Asciidoctor.
+         */
+        mode: DocumentOptions['mode'];
+        /**
+         * List of converters to use to parse the current document.
+         */
+        converters: CustomConverterFn[];
+        /**
+         * List of file system locations to templates to use when converting an
+         * Asciidoc document.
+         */
+        template: string;
+        /**
+         * Whether to search on sub-folders on the given template location
+         * for additional templates.
+         */
+        recursive: boolean;
+        /**
+         * List of custom template engines to use when producing the HTML5
+         * output for a given block. By default, *handlebars* and *nunjucks*
+         * are available.
+         *
+         * @default [new HandlebarsEngine(), new NunjucksEngine()]
+         */
+        templateEngines: Array<AbstractEngine & AsciidocTemplate>;
+    }>;
+    /**
+     * Options provided for the output of the preamble section, when
+     * there is one present in the parsed document.
+     */
+    preamble?: Partial<{
+        /**
+         * Whether to display the table of contents or not.
+         *
+         * @default true
+         */
+        tableOfContents: PreambleOptions['tableOfContents'];
+        /**
+         * How many levels of headings to include in the table of contents.
+         *
+         * @default 3
+         */
+        maxLevel: PreambleOptions['maxLevel'];
+        /**
+         * Whether to place the table of contents before or after the preamble, if
+         * there is one.
+         *
+         * @default "after"
+         */
+        position: PreambleOptions['position'];
+    }>;
+    /**
+     * Options for the Shiki highlighter.
+     */
+    syntaxHighlighting?: Partial<Pick<CodeToHastOptions, 'mergeWhitespaces' | 'tabindex'> & Pick<CodeOptionsMultipleThemes, 'cssVariablePrefix'> & {
+        /**
+         * The default theme applied to the code (via inline `color` style).
+         * The rest of the themes are applied via CSS variables, and toggled by CSS overrides.
+         *
+         * For example, if `defaultColor` is `light`, then `light` theme is applied to the code,
+         * and the `dark` theme and other custom themes are applied via CSS variables:
+         *
+         * ```html
+         * <span style="color:#{light};--shiki-dark:#{dark};--shiki-custom:#{custom};">code</span>
+         * ```
+         *
+         * When set to `false`, no default styles will be applied, and totally up to users to apply the styles:
+         *
+         * ```html
+         * <span style="--shiki-light:#{light};--shiki-dark:#{dark};--shiki-custom:#{custom};">code</span>
+         * ```
+         *
+         * When set to `light-dark()`, the default color will be rendered as `light-dark(#{light}, #{dark})`.
+         *
+         * ```html
+         * <span style="color:light-dark(#{light}, #{dark});--shiki-dark:#{dark};--shiki-custom:#{custom};">code</span>
+         * ```
+         *
+         * @default 'light-dark()'
+         */
+        defaultColor: Partial<Record<string, ThemeRegistrationAny | StringLiteralUnion<string>>>;
+        /**
+         * The syntax highlighter theme to use. It can be either a
+         * string that will apply for both light and dark mode by
+         * default (see defaultColor option), or an object with both
+         * "light" and "dark" properties. When passed as an object, it
+         * can have any arbitrary number of additional properties used
+         * to define custom themes.
+         *
+         * @default { light: 'catppuccin-latte', dark: 'catppuccin-macchiato' }
+         */
+        theme: BundledTheme | {
+            light: BundledTheme;
+            dark: BundledTheme;
+            [customTheme: string]: BundledTheme;
+        };
+    }>;
+};
+/**
+ * The types of context that an Asciidoc block can be.
+ */
+type NodeContext = 'admonition' | 'audio' | 'colist' | 'dlist' | 'document' | 'embedded' | 'example' | 'floating-title' | 'image' | 'inline_anchor' | 'inline_break' | 'inline_button' | 'inline_callout' | 'inline_footnote' | 'inline_image' | 'inline_indexterm' | 'inline_kbd' | 'inline_menu' | 'inline_quoted' | 'listing' | 'literal' | 'olist' | 'open' | 'outline' | 'page_break' | 'paragraph' | 'preamble' | 'quote' | 'section' | 'sidebar' | 'stem' | 'table' | 'thematic_break' | 'toc' | 'ulist' | 'verse' | 'video';
+type TemplateEngineOptions = {
+    rootDir: string;
+    recursive: boolean;
+};
+/**
+ * For engines that are modular and require third-party libraries like
+ * handlebars, nunjucks, etc.
+ */
+interface TemplateModule {
+    /**
+     * Loader function to import third-party modules asynchronously.
+     */
+    load(): Promise<void>;
+}
+/**
+ * Interface used by the default template engine, which can handle
+ * Asciidoctor.js' blocks directly. It should be the main entrypoint
+ * to the template rendering process.
+ */
+interface AsciidocTemplate {
+    renderNode(node: AbstractNode, options?: Record<string, unknown>): string;
+}
+/**
+ * Designates that the template will receive a file location that points
+ * to the template to render.
+ */
+interface FilesystemTemplate {
+    renderFile(filepath: string, options?: Record<string, unknown>): string;
+}
+/**
+ * Designates that the template will receive a string with the contents
+ * of the template, instead of a location to the template itself.
+ */
+interface RawTemplate {
+    renderString(content: string, options?: Record<string, unknown>): string;
+}
+
+export { type AsciidocLoader as A, type CustomConverterFactoryFn as C, type FilesystemTemplate as F, type NodeContext as N, type RawTemplate as R, type TemplateModule as T, type AsciidocTemplate as a, AbstractEngine as b };