@mdast2docx/image/dist/index.d.ts

MDAST to DOCX plugin for resolving and embedding images. Supports base64, URLs, and custom resolvers for seamless DOCX image integration.

import type { IImageOptions } from "docx";
import type { Image, IPlugin, Optional, SVG } from "@m2d/core";
import { type CacheConfigType } from "@m2d/core/cache";
/**
 * A resolver function that transforms an image `src` into
 * a `docx`-compatible `IImageOptions` object.
 *
 * @param src - Base64 or URL image source.
 * @param options - Current plugin options.
 * @param node - Image or SVG node in the Markdown AST.
 */
export type ImageResolver = (src: string, options: IDefaultImagePluginOptions, node?: Image | SVG) => Promise<IImageOptions>;
/**
 * Full configuration for the image plugin including defaulted and required options.
 */
export interface IDefaultImagePluginOptions {
    /** Scale factor for base64 (data URL) images. @default 3 */
    scale: number;
    /** Fallback format to convert unsupported image types. @default "png" */
    fallbackImageType: "png" | "jpg" | "bmp" | "gif";
    /** Image resolution function used to convert URL/base64/SVG to image options */
    imageResolver: ImageResolver;
    /** Max image width (in inches) for inserted image */
    maxW: number;
    /** Max image height (in inches) for inserted image */
    maxH: number;
    /** Optional placeholder image (base64 or URL) used on errors */
    placeholder?: string;
    /**
     * In-memory cache object, useful for cache sharing across plugins/tabs.
     */
    cache?: Record<string, Promise<unknown>>;
    /** Configure caching */
    cacheConfig?: CacheConfigType<IImageOptions>;
    /**
     * Optional salt string used to differentiate cache keys for similar images (e.g., dark/light theme).
     */
    salt?: string;
    /** Target resolution in DPI for calculating physical dimensions */
    dpi: number;
    /** Duration in minutes after which cached records are removed as stale. Default: 7 days (10080 minutes). */
    maxAgeMinutes: number;
    /**
     * Applies generic fixes to known SVG rendering issues (e.g., Mermaid pie chart title alignment).
     * Designed to be overridden to handle tool-specific quirks in generated SVGs.
     *
     * @param svg - Raw SVG string to transform.
     * @param metadata - Optional metadata such as diagram type or render info.
     * @returns Modified SVG string.
     */
    fixGeneratedSvg: (svg: string, metadata: any) => string;
}
/**
 * External plugin options accepted by consumers, omitting internal-only values.
 */
export type IImagePluginOptions = Optional<Omit<IDefaultImagePluginOptions, "dpi">>;
/**
 * Image plugin for `@m2d/core`.
 * Resolves all inline images (base64, SVG, URL) for DOCX generation.
 */
export declare const imagePlugin: (options?: IImagePluginOptions) => IPlugin;