@isdk/mdast-plus 0.1.2 → 0.2.0

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { Plugin, Processor } from 'unified';
+import { VFileCompatible, VFile } from 'vfile';
+
 // ## Interfaces
 
 /**
@@ -19,7 +22,7 @@
  * }
  * ```
  */
-interface Data$1 {}
+interface Data$2 {}
 
 /**
  * One place in a source file.
@@ -67,7 +70,7 @@ interface Position {
  * But for example in markdown, a `thematicBreak` (`***`), is neither literal
  * nor parent, but still a node.
  */
-interface Node$1 {
+interface Node$2 {
     /**
      * Node type.
      */
@@ -76,7 +79,7 @@ interface Node$1 {
     /**
      * Info from the ecosystem.
      */
-    data?: Data$1 | undefined;
+    data?: Data$2 | undefined;
 
     /**
      * Position of a node in a source document.
@@ -95,11 +98,11 @@ interface Node$1 {
  * For example, in XML, an element is a parent of different things, such as
  * comments, text, and further elements.
  */
-interface Parent$1 extends Node$1 {
+interface Parent$2 extends Node$2 {
     /**
      * List of children.
      */
-    children: Node$1[];
+    children: Node$2[];
 }
 
 // ## Enumeration
@@ -229,7 +232,7 @@ interface Resource {
  * }
  * ```
  */
-interface Data extends Data$1 {}
+interface Data$1 extends Data$2 {}
 
 // ## Content maps
 
@@ -367,7 +370,7 @@ interface PhrasingContentMap {
     link: Link;
     linkReference: LinkReference;
     strong: Strong;
-    text: Text;
+    text: Text$1;
 }
 
 /**
@@ -376,7 +379,7 @@ interface PhrasingContentMap {
  * To register custom mdast nodes, add them to {@link RootContentMap}.
  * They will be automatically added here.
  */
-type RootContent = RootContentMap[keyof RootContentMap];
+type RootContent$1 = RootContentMap$1[keyof RootContentMap$1];
 
 /**
  * Registry of all mdast nodes that can occur as children of {@link Root}.
@@ -397,7 +400,7 @@ type RootContent = RootContentMap[keyof RootContentMap];
  *
  * For a union of all {@link Root} children, see {@link RootContent}.
  */
-interface RootContentMap {
+interface RootContentMap$1 {
     blockquote: Blockquote;
     break: Break;
     code: Code;
@@ -420,7 +423,7 @@ interface RootContentMap {
     table: Table;
     tableCell: TableCell;
     tableRow: TableRow;
-    text: Text;
+    text: Text$1;
     thematicBreak: ThematicBreak;
     yaml: Yaml;
 }
@@ -492,7 +495,7 @@ interface TableContentMap {
  *
  * For a union of all registered mdast literals, see {@link Literals}.
  */
-interface Literal extends Node {
+interface Literal$1 extends Node$1 {
     /**
      * Plain-text value.
      */
@@ -512,11 +515,11 @@ interface Literal extends Node {
  *
  * For a union of all registered mdast nodes, see {@link Nodes}.
  */
-interface Node extends Node$1 {
+interface Node$1 extends Node$2 {
     /**
      * Info from the ecosystem.
      */
-    data?: Data | undefined;
+    data?: Data$1 | undefined;
 }
 
 /**
@@ -526,11 +529,11 @@ interface Node extends Node$1 {
  *
  * For a union of all registered mdast parents, see {@link Parents}.
  */
-interface Parent extends Node {
+interface Parent$1 extends Node$1 {
     /**
      * List of children.
      */
-    children: RootContent[];
+    children: RootContent$1[];
 }
 
 // ## Concrete nodes
@@ -538,7 +541,7 @@ interface Parent extends Node {
 /**
  * Markdown block quote.
  */
-interface Blockquote extends Parent {
+interface Blockquote extends Parent$1 {
     /**
      * Node type of mdast block quote.
      */
@@ -556,12 +559,12 @@ interface Blockquote extends Parent {
 /**
  * Info associated with mdast block quote nodes by the ecosystem.
  */
-interface BlockquoteData extends Data {}
+interface BlockquoteData extends Data$1 {}
 
 /**
  * Markdown break.
  */
-interface Break extends Node {
+interface Break extends Node$1 {
     /**
      * Node type of mdast break.
      */
@@ -575,12 +578,12 @@ interface Break extends Node {
 /**
  * Info associated with mdast break nodes by the ecosystem.
  */
-interface BreakData extends Data {}
+interface BreakData extends Data$1 {}
 
 /**
  * Markdown code (flow) (block).
  */
-interface Code extends Literal {
+interface Code extends Literal$1 {
     /**
      * Node type of mdast code (flow).
      */
@@ -604,12 +607,12 @@ interface Code extends Literal {
 /**
  * Info associated with mdast code (flow) (block) nodes by the ecosystem.
  */
-interface CodeData extends Data {}
+interface CodeData extends Data$1 {}
 
 /**
  * Markdown definition.
  */
-interface Definition extends Node, Association, Resource {
+interface Definition extends Node$1, Association, Resource {
     /**
      * Node type of mdast definition.
      */
@@ -623,12 +626,12 @@ interface Definition extends Node, Association, Resource {
 /**
  * Info associated with mdast definition nodes by the ecosystem.
  */
-interface DefinitionData extends Data {}
+interface DefinitionData extends Data$1 {}
 
 /**
  * Markdown GFM delete (strikethrough).
  */
-interface Delete extends Parent {
+interface Delete extends Parent$1 {
     /**
      * Node type of mdast GFM delete.
      */
@@ -646,12 +649,12 @@ interface Delete extends Parent {
 /**
  * Info associated with mdast GFM delete nodes by the ecosystem.
  */
-interface DeleteData extends Data {}
+interface DeleteData extends Data$1 {}
 
 /**
  * Markdown emphasis.
  */
-interface Emphasis extends Parent {
+interface Emphasis extends Parent$1 {
     /**
      * Node type of mdast emphasis.
      */
@@ -669,12 +672,12 @@ interface Emphasis extends Parent {
 /**
  * Info associated with mdast emphasis nodes by the ecosystem.
  */
-interface EmphasisData extends Data {}
+interface EmphasisData extends Data$1 {}
 
 /**
  * Markdown GFM footnote definition.
  */
-interface FootnoteDefinition extends Parent, Association {
+interface FootnoteDefinition extends Parent$1, Association {
     /**
      * Node type of mdast GFM footnote definition.
      */
@@ -692,12 +695,12 @@ interface FootnoteDefinition extends Parent, Association {
 /**
  * Info associated with mdast GFM footnote definition nodes by the ecosystem.
  */
-interface FootnoteDefinitionData extends Data {}
+interface FootnoteDefinitionData extends Data$1 {}
 
 /**
  * Markdown GFM footnote reference.
  */
-interface FootnoteReference extends Association, Node {
+interface FootnoteReference extends Association, Node$1 {
     /**
      * Node type of mdast GFM footnote reference.
      */
@@ -711,12 +714,12 @@ interface FootnoteReference extends Association, Node {
 /**
  * Info associated with mdast GFM footnote reference nodes by the ecosystem.
  */
-interface FootnoteReferenceData extends Data {}
+interface FootnoteReferenceData extends Data$1 {}
 
 /**
  * Markdown heading.
  */
-interface Heading extends Parent {
+interface Heading extends Parent$1 {
     /**
      * Node type of mdast heading.
      */
@@ -740,12 +743,12 @@ interface Heading extends Parent {
 /**
  * Info associated with mdast heading nodes by the ecosystem.
  */
-interface HeadingData extends Data {}
+interface HeadingData extends Data$1 {}
 
 /**
  * Markdown HTML.
  */
-interface Html extends Literal {
+interface Html extends Literal$1 {
     /**
      * Node type of mdast HTML.
      */
@@ -759,12 +762,12 @@ interface Html extends Literal {
 /**
  * Info associated with mdast HTML nodes by the ecosystem.
  */
-interface HtmlData extends Data {}
+interface HtmlData extends Data$1 {}
 
 /**
  * Markdown image.
  */
-interface Image extends Alternative, Node, Resource {
+interface Image extends Alternative, Node$1, Resource {
     /**
      * Node type of mdast image.
      */
@@ -778,12 +781,12 @@ interface Image extends Alternative, Node, Resource {
 /**
  * Info associated with mdast image nodes by the ecosystem.
  */
-interface ImageData extends Data {}
+interface ImageData extends Data$1 {}
 
 /**
  * Markdown image reference.
  */
-interface ImageReference extends Alternative, Node, Reference {
+interface ImageReference extends Alternative, Node$1, Reference {
     /**
      * Node type of mdast image reference.
      */
@@ -797,12 +800,12 @@ interface ImageReference extends Alternative, Node, Reference {
 /**
  * Info associated with mdast image reference nodes by the ecosystem.
  */
-interface ImageReferenceData extends Data {}
+interface ImageReferenceData extends Data$1 {}
 
 /**
  * Markdown code (text) (inline).
  */
-interface InlineCode extends Literal {
+interface InlineCode extends Literal$1 {
     /**
      * Node type of mdast code (text).
      */
@@ -816,12 +819,12 @@ interface InlineCode extends Literal {
 /**
  * Info associated with mdast code (text) (inline) nodes by the ecosystem.
  */
-interface InlineCodeData extends Data {}
+interface InlineCodeData extends Data$1 {}
 
 /**
  * Markdown link.
  */
-interface Link extends Parent, Resource {
+interface Link extends Parent$1, Resource {
     /**
      * Node type of mdast link.
      */
@@ -839,12 +842,12 @@ interface Link extends Parent, Resource {
 /**
  * Info associated with mdast link nodes by the ecosystem.
  */
-interface LinkData extends Data {}
+interface LinkData extends Data$1 {}
 
 /**
  * Markdown link reference.
  */
-interface LinkReference extends Parent, Reference {
+interface LinkReference extends Parent$1, Reference {
     /**
      * Node type of mdast link reference.
      */
@@ -862,12 +865,12 @@ interface LinkReference extends Parent, Reference {
 /**
  * Info associated with mdast link reference nodes by the ecosystem.
  */
-interface LinkReferenceData extends Data {}
+interface LinkReferenceData extends Data$1 {}
 
 /**
  * Markdown list.
  */
-interface List extends Parent {
+interface List extends Parent$1 {
     /**
      * Node type of mdast list.
      */
@@ -899,12 +902,12 @@ interface List extends Parent {
 /**
  * Info associated with mdast list nodes by the ecosystem.
  */
-interface ListData extends Data {}
+interface ListData extends Data$1 {}
 
 /**
  * Markdown list item.
  */
-interface ListItem extends Parent {
+interface ListItem extends Parent$1 {
     /**
      * Node type of mdast list item.
      */
@@ -934,12 +937,12 @@ interface ListItem extends Parent {
 /**
  * Info associated with mdast list item nodes by the ecosystem.
  */
-interface ListItemData extends Data {}
+interface ListItemData extends Data$1 {}
 
 /**
  * Markdown paragraph.
  */
-interface Paragraph extends Parent {
+interface Paragraph extends Parent$1 {
     /**
      * Node type of mdast paragraph.
      */
@@ -957,14 +960,14 @@ interface Paragraph extends Parent {
 /**
  * Info associated with mdast paragraph nodes by the ecosystem.
  */
-interface ParagraphData extends Data {}
+interface ParagraphData extends Data$1 {}
 
 /**
  * Document fragment or a whole document.
  *
  * Should be used as the root of a tree and must not be used as a child.
  */
-interface Root extends Parent {
+interface Root$1 extends Parent$1 {
     /**
      * Node type of mdast root.
      */
@@ -972,18 +975,18 @@ interface Root extends Parent {
     /**
      * Data associated with the mdast root.
      */
-    data?: RootData | undefined;
+    data?: RootData$1 | undefined;
 }
 
 /**
  * Info associated with mdast root nodes by the ecosystem.
  */
-interface RootData extends Data {}
+interface RootData$1 extends Data$1 {}
 
 /**
  * Markdown strong.
  */
-interface Strong extends Parent {
+interface Strong extends Parent$1 {
     /**
      * Node type of mdast strong.
      */
@@ -1001,12 +1004,12 @@ interface Strong extends Parent {
 /**
  * Info associated with mdast strong nodes by the ecosystem.
  */
-interface StrongData extends Data {}
+interface StrongData extends Data$1 {}
 
 /**
  * Markdown GFM table.
  */
-interface Table extends Parent {
+interface Table extends Parent$1 {
     /**
      * Node type of mdast GFM table.
      */
@@ -1028,12 +1031,12 @@ interface Table extends Parent {
 /**
  * Info associated with mdast GFM table nodes by the ecosystem.
  */
-interface TableData extends Data {}
+interface TableData extends Data$1 {}
 
 /**
  * Markdown GFM table row.
  */
-interface TableRow extends Parent {
+interface TableRow extends Parent$1 {
     /**
      * Node type of mdast GFM table row.
      */
@@ -1051,12 +1054,12 @@ interface TableRow extends Parent {
 /**
  * Info associated with mdast GFM table row nodes by the ecosystem.
  */
-interface TableRowData extends Data {}
+interface TableRowData extends Data$1 {}
 
 /**
  * Markdown GFM table cell.
  */
-interface TableCell extends Parent {
+interface TableCell extends Parent$1 {
     /**
      * Node type of mdast GFM table cell.
      */
@@ -1074,12 +1077,12 @@ interface TableCell extends Parent {
 /**
  * Info associated with mdast GFM table cell nodes by the ecosystem.
  */
-interface TableCellData extends Data {}
+interface TableCellData extends Data$1 {}
 
 /**
  * Markdown text.
  */
-interface Text extends Literal {
+interface Text$1 extends Literal$1 {
     /**
      * Node type of mdast text.
      */
@@ -1087,18 +1090,18 @@ interface Text extends Literal {
     /**
      * Data associated with the mdast text.
      */
-    data?: TextData | undefined;
+    data?: TextData$1 | undefined;
 }
 
 /**
  * Info associated with mdast text nodes by the ecosystem.
  */
-interface TextData extends Data {}
+interface TextData$1 extends Data$1 {}
 
 /**
  * Markdown thematic break (horizontal rule).
  */
-interface ThematicBreak extends Node {
+interface ThematicBreak extends Node$1 {
     /**
      * Node type of mdast thematic break.
      */
@@ -1112,12 +1115,12 @@ interface ThematicBreak extends Node {
 /**
  * Info associated with mdast thematic break nodes by the ecosystem.
  */
-interface ThematicBreakData extends Data {}
+interface ThematicBreakData extends Data$1 {}
 
 /**
  * Markdown YAML.
  */
-interface Yaml extends Literal {
+interface Yaml extends Literal$1 {
     /**
      * Node type of mdast YAML.
      */
@@ -1131,7 +1134,29 @@ interface Yaml extends Literal {
 /**
  * Info associated with mdast YAML nodes by the ecosystem.
  */
-interface YamlData extends Data {}
+interface YamlData extends Data$1 {}
+
+// ## Interfaces
+
+/**
+ * Info associated with hast nodes by the ecosystem.
+ *
+ * This space is guaranteed to never be specified by unist or hast.
+ * But you can use it in utilities and plugins to store data.
+ *
+ * This type can be augmented to register custom data.
+ * For example:
+ *
+ * ```ts
+ * declare module 'hast' {
+ *   interface Data {
+ *     // `someNode.data.myId` is typed as `number | undefined`
+ *     myId?: number | undefined
+ *   }
+ * }
+ * ```
+ */
+interface Data extends Data$2 {}
 
 /**
  * Info associated with an element.
@@ -1140,83 +1165,316 @@ interface Properties {
     [PropertyName: string]: boolean | number | string | null | undefined | Array<string | number>;
 }
 
+// ## Content maps
+
 /**
- * Stages for mdast-plus pipeline processing.
+ * Union of registered hast nodes that can occur in {@link Element}.
+ *
+ * To register mote custom hast nodes, add them to {@link ElementContentMap}.
+ * They will be automatically added here.
  */
-type Stage = 'normalize' | 'compile' | 'finalize';
+type ElementContent = ElementContentMap[keyof ElementContentMap];
+
 /**
- * Definition for an mdast plugin.
+ * Registry of all hast nodes that can occur as children of {@link Element}.
+ *
+ * For a union of all {@link Element} children, see {@link ElementContent}.
  */
-interface MdastPlugin {
-    /** Plugin name */
-    name: string;
-    /** Processing stage the plugin belongs to */
-    stage?: Stage;
-    /** Execution order within the stage (lower numbers run first) */
-    order?: number;
-    /** Transformation function */
-    transform: (tree: Root, ctx: any) => Promise<void> | void;
+interface ElementContentMap {
+    comment: Comment;
+    element: Element;
+    text: Text;
 }
+
 /**
- * Definition for an mdast format (parser/stringifier).
+ * Union of registered hast nodes that can occur in {@link Root}.
+ *
+ * To register custom hast nodes, add them to {@link RootContentMap}.
+ * They will be automatically added here.
  */
-interface MdastFormatDefinition {
-    /** Function to register parser plugins */
-    parse?: (processor: any) => void;
-    /** Function to register stringifier plugins */
-    stringify?: (processor: any) => void;
+type RootContent = RootContentMap[keyof RootContentMap];
+
+/**
+ * Registry of all hast nodes that can occur as children of {@link Root}.
+ *
+ * > 👉 **Note**: {@link Root} does not need to be an entire document.
+ * > it can also be a fragment.
+ *
+ * For a union of all {@link Root} children, see {@link RootContent}.
+ */
+interface RootContentMap {
+    comment: Comment;
+    doctype: Doctype;
+    element: Element;
+    text: Text;
 }
+
+// ## Abstract nodes
+
 /**
- * Represents an asset (e.g., image) extracted during processing.
+ * Abstract hast node.
+ *
+ * This interface is supposed to be extended.
+ * If you can use {@link Literal} or {@link Parent}, you should.
+ * But for example in HTML, a `Doctype` is neither literal nor parent, but
+ * still a node.
+ *
+ * To register custom hast nodes, add them to {@link RootContentMap} and other
+ * places where relevant (such as {@link ElementContentMap}).
+ *
+ * For a union of all registered hast nodes, see {@link Nodes}.
  */
-interface MdastAsset {
-    /** Relative path or identifier for the asset */
-    path: string;
-    /** MIME type of the asset */
-    contentType: string;
-    /** Raw content as bytes */
-    bytes: Uint8Array;
+interface Node extends Node$2 {
+    /**
+     * Info from the ecosystem.
+     */
+    data?: Data | undefined;
 }
+
 /**
- * Result of a conversion process.
- * @template T - The type of the main content (default: string)
+ * Abstract hast node that contains the smallest possible value.
+ *
+ * This interface is supposed to be extended if you make custom hast nodes.
+ *
+ * For a union of all registered hast literals, see {@link Literals}.
  */
-interface ConvertResult<T = string> {
-    /** The converted content */
-    content: T;
-    /** Extracted assets */
-    assets: MdastAsset[];
+interface Literal extends Node {
+    /**
+     * Plain-text value.
+     */
+    value: string;
 }
+
 /**
- * Original metadata for a node.
+ * Abstract hast node that contains other hast nodes (*children*).
+ *
+ * This interface is supposed to be extended if you make custom hast nodes.
+ *
+ * For a union of all registered hast parents, see {@link Parents}.
+ */
+interface Parent extends Node {
+    /**
+     * List of children.
+     */
+    children: RootContent[];
+}
+
+// ## Concrete nodes
+
+/**
+ * HTML comment.
+ */
+interface Comment extends Literal {
+    /**
+     * Node type of HTML comments in hast.
+     */
+    type: "comment";
+    /**
+     * Data associated with the comment.
+     */
+    data?: CommentData | undefined;
+}
+
+/**
+ * Info associated with hast comments by the ecosystem.
+ */
+interface CommentData extends Data {}
+
+/**
+ * HTML document type.
+ */
+interface Doctype extends Node$2 {
+    /**
+     * Node type of HTML document types in hast.
+     */
+    type: "doctype";
+    /**
+     * Data associated with the doctype.
+     */
+    data?: DoctypeData | undefined;
+}
+
+/**
+ * Info associated with hast doctypes by the ecosystem.
+ */
+interface DoctypeData extends Data {}
+
+/**
+ * HTML element.
+ */
+interface Element extends Parent {
+    /**
+     * Node type of elements.
+     */
+    type: "element";
+    /**
+     * Tag name (such as `'body'`) of the element.
+     */
+    tagName: string;
+    /**
+     * Info associated with the element.
+     */
+    properties: Properties;
+    /**
+     * Children of element.
+     */
+    children: ElementContent[];
+    /**
+     * When the `tagName` field is `'template'`, a `content` field can be
+     * present.
+     */
+    content?: Root | undefined;
+    /**
+     * Data associated with the element.
+     */
+    data?: ElementData | undefined;
+}
+
+/**
+ * Info associated with hast elements by the ecosystem.
+ */
+interface ElementData extends Data {}
+
+/**
+ * Document fragment or a whole document.
+ *
+ * Should be used as the root of a tree and must not be used as a child.
+ *
+ * Can also be used as the value for the content field on a `'template'` element.
+ */
+interface Root extends Parent {
+    /**
+     * Node type of hast root.
+     */
+    type: "root";
+    /**
+     * Children of root.
+     */
+    children: RootContent[];
+    /**
+     * Data associated with the hast root.
+     */
+    data?: RootData | undefined;
+}
+
+/**
+ * Info associated with hast root nodes by the ecosystem.
+ */
+interface RootData extends Data {}
+
+/**
+ * HTML character data (plain text).
+ */
+interface Text extends Literal {
+    /**
+     * Node type of HTML character data (plain text) in hast.
+     */
+    type: "text";
+    /**
+     * Data associated with the text.
+     */
+    data?: TextData | undefined;
+}
+
+/**
+ * Info associated with hast texts by the ecosystem.
+ */
+interface TextData extends Data {}
+
+/**
+ * PipelineStage defines the execution order of plugins in the processing pipeline.
+ * Plugins are sorted and executed in ascending order based on these stage values.
+ */
+declare enum PipelineStage {
+    /** Initial stage for parsing raw input (e.g., string to AST). */
+    parse = 0,
+    /** Normalization stage for cleaning up and canonicalizing the AST (e.g., GFM, Directives). */
+    normalize = 100,
+    /** Transformation stage for semantic changes and custom high-level logic. */
+    compile = 200,
+    /** Finalization stage for preparing the AST for output (e.g., Sanitize, bridge to HAST). */
+    finalize = 300,
+    /** Final stage for serializing the AST to the target format result. */
+    stringify = 400
+}
+/** The default stage assigned to a plugin if none is specified. */
+declare const DefaultPipelineStage = PipelineStage.compile;
+/** String names corresponding to the PipelineStage levels. */
+type PipelineStageName = keyof typeof PipelineStage;
+/**
+ * Configuration for a plugin within the mdast-plus pipeline.
+ * It wraps a standard unified plugin with execution metadata.
+ */
+interface MdastPlugin {
+    /**
+     * Optional name for the plugin.
+     * Used for identification in overrides and logging.
+     * If not provided, defaults to the plugin function's name.
+     */
+    name?: string;
+    /** The standard unified plugin (attacher) function. */
+    plugin: Plugin<any[], any, any>;
+    /**
+     * Arguments passed to the plugin.
+     * MUST be an array of arguments (e.g., [optionsObject]).
+     */
+    options?: any[];
+    /** The stage in which this plugin should run. */
+    stage?: PipelineStage | PipelineStageName;
+    /** Execution priority within the same stage. Lower values run earlier. */
+    order?: number;
+    /**
+     * If true, this plugin is considered the "main" plugin for its stage.
+     * When multiple plugins exist in the same stage, a 'main' plugin will
+     * replace the default (first) plugin of that stage.
+     */
+    main?: boolean;
+    /** Run this plugin before the named plugin (within the same stage). */
+    before?: string;
+    /** Run this plugin after the named plugin (within the same stage). */
+    after?: string;
+}
+/**
+ * Defines a document format, encompassing its input (parsing) and output (serialization) strategies.
+ */
+interface MdastFormat {
+    /** Unique identifier for the format (e.g., 'markdown', 'html'). */
+    id: string;
+    /** Human-readable title. */
+    title?: string;
+    /** File extensions associated with this format. */
+    extensions?: string[];
+    /** MIME types associated with this format. */
+    mediaTypes?: string[];
+    /** Plugins used for reading this format into a standard AST (Parser + Normalizer). */
+    input?: MdastPlugin[];
+    /** Plugins used for serializing the AST into this format (Finalizer + Stringifier). */
+    output?: MdastPlugin[];
+}
+/**
+ * Metadata capturing the origin of a node during conversion.
  */
 interface MdastDataOrigin {
-    /** Source format */
+    /** The original source format. */
     format: 'docx' | 'notion' | 'html' | 'markdown' | 'latex' | string;
-    /** Raw data from the source */
+    /** The raw content from the source before conversion. */
     raw?: unknown;
-    /** Hash of the source content */
+    /** Hash used for caching or change detection. */
     hash?: string;
     [k: string]: unknown;
 }
-/**
- * mdast node for highlighted text (mark).
- */
-interface MdastMark extends Parent$1 {
+/** Represents a highlighted text (mark) node in mdast. */
+interface MdastMark extends Parent$2 {
     type: 'mark';
     children: PhrasingContent[];
 }
-/**
- * mdast node for subscript text.
- */
-interface MdastSub extends Parent$1 {
+/** Represents a subscript text node in mdast. */
+interface MdastSub extends Parent$2 {
     type: 'sub';
     children: PhrasingContent[];
 }
-/**
- * mdast node for superscript text.
- */
-interface MdastSup extends Parent$1 {
+/** Represents a superscript text node in mdast. */
+interface MdastSup extends Parent$2 {
     type: 'sup';
     children: PhrasingContent[];
 }
@@ -1228,6 +1486,14 @@ declare module 'mdast' {
         hProperties?: Properties;
         /** Source origin information */
         _origin?: MdastDataOrigin;
+        readability?: {
+            title: string;
+            byline: string;
+            excerpt: string;
+            siteName: string;
+            lang: string;
+        };
+        [k: string]: any;
     }
     interface CodeData extends Data {
         /** Title of the code block */
@@ -1249,128 +1515,227 @@ declare module 'mdast' {
         sup: MdastSup;
     }
 }
+
 /**
- * Interface for reading input into an mdast tree.
- * @template I - Input type
+ * Base implementation of the fluent mdast processing pipeline.
+ * Manages the plugin registry and the execution queue.
  */
-interface MdastReader<I> {
+declare class MdastBasePipeline {
+    private static readonly registry;
     /**
-     * Reads input and returns an mdast Root node.
-     * @param input - The input to read
+     * Registers a global document format.
+     * @param format - The format definition to register.
      */
-    read(input: I): Promise<Root>;
-}
-/**
- * Interface for transforming an mdast tree.
- */
-interface MdastTransformer {
+    static register(format: MdastFormat): void;
     /**
-     * Transforms the given mdast tree.
-     * @param tree - The Root node to transform
+     * Retrieves a registered format by its ID.
+     * @param id - The format identifier.
+     * @returns The format definition or undefined if not found.
      */
-    transform(tree: Root): Promise<{
-        tree: Root;
-        assets?: MdastAsset[];
-    }>;
-}
-/**
- * Interface for writing an mdast tree to an output format.
- * @template Output - Output type (default: string)
- */
-interface MdastWriter<Output = string> {
+    static getFormat(id: string): MdastFormat | undefined;
+    protected input: VFileCompatible;
+    protected queue: MdastPlugin[];
+    protected _data: Record<string, any>;
     /**
-     * Writes the mdast tree to the target output.
-     * @param tree - The Root node to write
-     * @param assets - Optional assets to include
+     * Initializes a new pipeline instance with the given input.
+     * @param input - Content to process (string, Buffer, VFile, or AST Node).
      */
-    write(tree: Root, assets?: MdastAsset[]): Promise<ConvertResult<Output>>;
-}
-
-/**
- * Fluent processor for mdast transformations.
- * Allows chaining configuration and finally converting to a target format.
- */
-declare class FluentProcessor {
-    /** Map of registered format definitions */
-    static formats: Record<string, MdastFormatDefinition>;
+    constructor(input: VFileCompatible);
+    /**
+     * Configures global data for the pipeline, which will be available to all plugins via this.data().
+     * @param key - Data key or a record of multiple data entries.
+     * @param value - Value to set (if key is a string).
+     * @returns The pipeline instance for chaining.
+     */
+    data(key: string | Record<string, any>, value?: any): this;
+    /**
+     * Instance-level access to the global format registry.
+     */
+    getFormat(id: string): MdastFormat | undefined;
+    /**
+     * Resolves a format identifier or object to a valid MdastFormat.
+     * @private
+     */
+    private resolveFormat;
+    /**
+     * Normalizes a plugin entry for runtime execution.
+     * @protected
+     */
+    protected toRuntimeEntry(entry: MdastPlugin, defaultStage: PipelineStage, overrides?: Record<string, any>): MdastPlugin & {
+        stage: PipelineStage;
+    };
+    /**
+     * Ensures that input plugins (parser, normalizers) are present in the queue.
+     * Adds implicit plugins if no parser is detected.
+     * @protected
+     */
+    protected ensureInputPlugins(queue: MdastPlugin[], overrides?: Record<string, any>, maxStage?: PipelineStage): void;
     /**
-     * Registers a new format definition.
-     * @param name - The name of the format (e.g., 'docx')
-     * @param definition - The format definition containing parse/stringify logic
+     * Configures the input format and adds its associated plugins to the pipeline.
+     * @param fmt - Format ID or definition.
+     * @param overrides - Optional map to override plugin options by plugin name.
+     * @returns The pipeline instance for chaining.
      */
-    static registerFormat(name: string, definition: MdastFormatDefinition): void;
-    private processor;
-    private input;
-    private inputFormat;
-    private plugins;
-    private globalData;
+    from(fmt: string | MdastFormat, overrides?: Record<string, any>): this;
     /**
-     * Creates a new FluentProcessor instance.
-     * @param input - The input content (string or mdast tree)
+     * Processes the pipeline and serializes the result into the specified format.
+     * @param fmt - Target format ID or definition.
+     * @param overrides - Optional map to override plugin options.
+     * @returns A promise resolving to a VFile containing the result.
      */
-    constructor(input: any);
+    to(fmt: string | MdastFormat, overrides?: Record<string, any>): Promise<VFile>;
     /**
-     * Specifies the input format.
-     * @param format - The input format name (default: 'markdown')
+     * Adds a plugin or an array of plugins to the pipeline's compile stage.
+     * @param plugin - The unified plugin function, a MdastPlugin object, or an array of them.
+     * @param options - Arguments for the plugin(s).
+     * @returns The pipeline instance for chaining.
      */
-    from(format: string): this;
+    use(plugin: Plugin | MdastPlugin | (Plugin | MdastPlugin)[], ...options: any[]): this;
     /**
-     * Adds a plugin to the processing pipeline.
-     * @param plugin - The mdast plugin to use
+     * Adds a plugin or an array of plugins to the pipeline at a specific stage.
+     * @param stage - The stage name or numeric value.
+     * @param plugin - The unified plugin function, a MdastPlugin object, or an array of them.
+     * @param options - Arguments for the plugin(s).
+     * @returns The pipeline instance for chaining.
      */
-    use(plugin: MdastPlugin): this;
+    useAt(stage: PipelineStageName, plugin: Plugin | MdastPlugin | (Plugin | MdastPlugin)[], ...options: any[]): this;
     /**
-     * Merges global data into the processor.
-     * @param data - Key-value pairs to store in global data
+     * Adds a plugin or an array of plugins to the pipeline. The stage is taken from the plugin object(s).
+     * @param plugin - The MdastPlugin object or an array of them.
+     * @param options - Arguments for the plugin(s) (overrides plugin.options if provided).
+     * @returns The pipeline instance for chaining.
      */
-    data(data: Record<string, any>): this;
+    useAt(plugin: MdastPlugin | (Plugin | MdastPlugin)[], ...options: any[]): this;
     /**
-     * Converts the input content to the specified format.
-     * @param format - The output format name
-     * @returns A promise resolving to the conversion result (content and assets)
+     * Sets the priority order for the most recently added plugin.
+     * Plugins with lower order run earlier within the same stage.
+     * @param order - Numeric priority.
+     * @returns The pipeline instance for chaining.
      */
-    to(format: string): Promise<ConvertResult>;
+    priority(order: number): this;
     /**
-     * Helper to convert content to Markdown.
-     * @returns A promise resolving to the Markdown string
+     * Assembles a unified processor based on the sorted plugin queue.
+     * @protected
+     */
+    protected assembleProcessor(queue: MdastPlugin[]): Processor;
+}
+/**
+ * Extended pipeline with convenience methods for common formats.
+ */
+declare class MdastPipeline extends MdastBasePipeline {
+    /**
+     * Finalizes the pipeline and returns the result as a Markdown string.
      */
     toMarkdown(): Promise<string>;
     /**
-     * Helper to convert content to HTML.
-     * @returns A promise resolving to the HTML string
+     * Finalizes the pipeline and returns a VFile containing the Markdown result.
      */
-    toHTML(): Promise<string>;
+    toMarkdownVFile(): Promise<VFile>;
+    /**
+     * Finalizes the pipeline and returns the result as an HTML string.
+     */
+    toHtml(): Promise<string>;
     /**
-     * Helper to get the processed mdast tree.
-     * @returns A promise resolving to the mdast Root node
+     * Finalizes the pipeline and returns a VFile containing the HTML result.
      */
-    toAST(): Promise<Root>;
+    toHtmlVFile(): Promise<VFile>;
+    /**
+     * Finalizes the pipeline and returns the resulting AST (Root node).
+     * @param options - Configuration for the extraction.
+     * @param options.stage - Run the pipeline up to this stage only.
+     * @param options.overrides - Map for plugin option overrides.
+     */
+    toAst(options?: {
+        stage?: PipelineStageName;
+        overrides?: Record<string, any>;
+    }): Promise<Root$1>;
+    /** Alias for toHtml() */
+    toHTML(): Promise<string>;
+    /** Alias for toAst() */
+    toAST(options?: {
+        stage?: PipelineStageName;
+        overrides?: Record<string, any>;
+    }): Promise<Root$1>;
 }
 /**
  * Entry point for the fluent mdast-plus API.
  * @param input - The input content (string or mdast tree)
  * @returns A FluentProcessor instance
  */
-declare function mdast(input: any): FluentProcessor;
+declare function mdast(input: VFileCompatible): MdastPipeline;
+
+/**
+ * Markdown format definition.
+ *
+ * Supports GFM, Directives, Math, and Frontmatter.
+ * Provides a bidirectional mapping between Markdown strings and mdast-plus ASTs.
+ */
+declare const markdownFormat: MdastFormat;
 
 /**
- * Common remark configuration for Markdown.
+ * HTML format definition.
+ *
+ * Provides a bidirectional mapping between HTML strings and mdast-plus ASTs.
+ * Includes built-in sanitization and support for table spans and image dimensions.
+ */
+declare const htmlFormat: MdastFormat;
+
+/**
+ * Pass-through compiler that returns the AST as-is.
+ * Essential for unified processes that should output an object (the AST)
+ * instead of a serialized string.
  */
-declare function markdownCommon(this: any): void;
+declare function astCompiler(this: any): void;
 /**
- * Markdown format definition for FluentProcessor.
- * Handles both parsing (Markdown -> MDAST) and stringifying (MDAST -> Markdown).
+ * Parser for stringified JSON AST input.
+ * Allows the pipeline to accept a JSON string and treat it as a unist tree.
  */
-declare const markdownFormat: MdastFormatDefinition;
+declare function jsonParser(this: any): void;
+/**
+ * AST (MDAST) format definition.
+ * Supports reading from JSON strings and provides full normalization
+ * through the standard mdast-plus plugin set.
+ */
+declare const astFormat: MdastFormat;
 
+interface ReadabilityOptions {
+    enable?: boolean;
+    readability?: Record<string, any>;
+    jsdom?: Record<string, any>;
+}
 /**
- * Standard compiler/stringifier for HTML.
+ * A unified/rehype plugin that uses Mozilla's Readability to parse the input HTML.
  */
-declare function htmlStringify(this: any): void;
+declare const htmlReadability: Plugin<[(ReadabilityOptions | boolean)?], string, Root>;
 /**
- * HTML format definition for FluentProcessor.
- * Handles both parsing (HTML -> MDAST) and stringifying (MDAST -> HTML).
+ * Pre-configured MdastPlugin for html-readability.
  */
-declare const htmlFormat: MdastFormatDefinition;
+declare const htmlReadabilityPlugin: {
+    name: string;
+    plugin: Plugin<[(boolean | ReadabilityOptions | undefined)?], string, Root>;
+    stage: PipelineStage;
+};
+/**
+ * Plugin to restore readability metadata after HAST to MDAST conversion.
+ */
+declare const restoreReadabilityMetaPlugin: {
+    name: string;
+    plugin: () => (tree: any, file: any) => void;
+    stage: PipelineStage;
+    after: string;
+};
+/**
+ * Combined plugins for HTML readability.
+ */
+declare const htmlReadabilityPlugins: ({
+    name: string;
+    plugin: Plugin<[(boolean | ReadabilityOptions | undefined)?], string, Root>;
+    stage: PipelineStage;
+} | {
+    name: string;
+    plugin: () => (tree: any, file: any) => void;
+    stage: PipelineStage;
+    after: string;
+})[];
 
-export { type ConvertResult, FluentProcessor, type MdastAsset, type MdastDataOrigin, type MdastFormatDefinition, type MdastMark, type MdastPlugin, type MdastReader, type MdastSub, type MdastSup, type MdastTransformer, type MdastWriter, type Stage, htmlFormat, htmlStringify, markdownCommon, markdownFormat, mdast };
+export { DefaultPipelineStage, MdastBasePipeline, type MdastDataOrigin, type MdastFormat, type MdastMark, MdastPipeline, type MdastPlugin, type MdastSub, type MdastSup, PipelineStage, type PipelineStageName, type ReadabilityOptions, astCompiler, astFormat, htmlFormat, htmlReadability, htmlReadabilityPlugin, htmlReadabilityPlugins, jsonParser, markdownFormat, mdast, restoreReadabilityMetaPlugin };