@markuplint/markdown-parser 5.0.0-rc.2 → 5.0.0-rc.5

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.0.0-rc.5](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.4...v5.0.0-rc.5) (2026-08-28)
+
+### Features
+
+- **markdown-parser,pug-parser:** force fragment parsing for embedded HTML ([57c4172](https://github.com/markuplint/markuplint/commit/57c4172d5a68adb7e20a4f4e4d8dbe802983e3ca)), closes [#3844](https://github.com/markuplint/markuplint/issues/3844)
+- **markdown-parser,pug-parser:** forward embedded HTML parseErrors to outer document ([9ec7988](https://github.com/markuplint/markuplint/commit/9ec79882840cbedd76c5b8f774ff10c876d2c858)), closes [#3844](https://github.com/markuplint/markuplint/issues/3844)
+
+# [5.0.0-rc.4](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.3...v5.0.0-rc.4) (2026-04-19)
+
+**Note:** Version bump only for package @markuplint/markdown-parser
+
+# [5.0.0-rc.3](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.2...v5.0.0-rc.3) (2026-04-19)
+
+**Note:** Version bump only for package @markuplint/markdown-parser
+
 # [5.0.0-rc.2](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.1...v5.0.0-rc.2) (2026-04-15)
 
 **Note:** Version bump only for package @markuplint/markdown-parser

package/lib/markdown-aware-parser.d.ts

@@ -4,163 +4,56 @@ import type { Code, Definition, Image, InlineCode, Link, List, RootContent, Tabl
 import { Parser } from '@markuplint/parser-utils';
 type MdastNode = RootContent;
 /**
- * Abstract base class for parsers that handle Markdown content.
- *
- * Provides shared logic for converting mdast nodes (headings, links, images,
- * lists, code, tables, etc.) into markuplint's AST. Both MarkdownParser and
- * MDXParser extend this class to avoid code duplication.
+ * Extends `Parser<MdastNode>` rather than `HtmlParser`: an earlier design
+ * extended `HtmlParser` and treated Markdown as opaque psblock nodes, which
+ * left Markdown constructs invisible to rules. Converting them to their HTML
+ * equivalents (with synthesized attributes such as `src`/`alt` from
+ * `![alt](src)`) is what makes Markdown content lintable.
  */
 export declare abstract class MarkdownAwareParser extends Parser<MdastNode> {
     #private;
-    /**
-     * Stores link/image reference definitions (`[id]: url "title"`)
-     * extracted during tokenization for resolving linkReference/imageReference nodes.
-     */
     protected definitions: Map<string, Definition>;
     constructor(options?: ParserOptions);
     /**
-     * Resets mutable state accumulated during a previous `parse()` call.
-     *
      * Must be called at the beginning of every `tokenize()` invocation to
      * prevent definitions, header-row offsets, and cell-name state from
      * leaking across successive `parse()` calls on the same parser instance.
      */
     protected resetMarkdownState(): void;
     /**
-     * Adjusts the flattened node list for Markdown output.
-     *
      * Disables whitespace and invalid-node exposure because Markdown
      * generates only synthetic elements with no real HTML whitespace tokens.
-     *
-     * @param nodeList - The flattened node tree produced by the base class.
-     * @returns The adjusted node list.
      */
     afterFlattenNodes(nodeList: readonly MLASTNodeTreeItem[]): readonly MLASTNodeTreeItem[];
     /**
-     * Creates a synthetic HTML attribute token for Markdown-derived elements.
-     *
      * The attribute positions point to the element's own token range because
      * Markdown syntax does not have discrete attribute source positions.
-     *
-     * @param name - The attribute name (e.g., `"href"`, `"alt"`).
-     * @param value - The attribute value extracted from Markdown syntax.
-     * @param token - The source token whose position is reused for the attribute.
-     * @returns A fully-formed HTML attribute node.
      */
     protected createSyntheticAttr(name: string, value: string, token: Token): MLASTHTMLAttr;
-    /**
-     * Builds a generic HTML element node from a Markdown construct.
-     *
-     * @param token - The source token covering the entire construct.
-     * @param nodeName - The HTML element name (e.g., `"p"`, `"h1"`, `"li"`).
-     * @param childNodes - The mdast children to recurse into.
-     * @param depth - Current nesting depth in the AST.
-     * @param parentNode - Parent AST node, or `null` for top-level nodes.
-     * @param attributes - Optional pre-built attributes to attach.
-     * @returns The element node followed by its descendants.
-     */
     protected visitMarkdownElement(token: Token, nodeName: string, childNodes: readonly MdastNode[], depth: number, parentNode: MLASTParentNode | null, attributes?: readonly MLASTAttr[]): readonly MLASTNodeTreeItem[];
-    /**
-     * Builds an `<a>` element with `href` (and optionally `title`) attributes.
-     *
-     * @param originNode - The mdast `link` node.
-     * @param token - The source token covering the link.
-     * @param depth - Current nesting depth.
-     * @param parentNode - Parent AST node, or `null` for top-level.
-     * @returns The `<a>` element node and its descendants.
-     */
     protected visitLinkElement(originNode: Link, token: Token, depth: number, parentNode: MLASTParentNode | null): readonly MLASTNodeTreeItem[];
-    /**
-     * Builds an `<img>` element with `src`, `alt`, and optionally `title` attributes.
-     *
-     * @param originNode - The mdast `image` node.
-     * @param token - The source token covering the image.
-     * @param depth - Current nesting depth.
-     * @param parentNode - Parent AST node, or `null` for top-level.
-     * @returns The `<img>` element node.
-     */
     protected visitImageElement(originNode: Image, token: Token, depth: number, parentNode: MLASTParentNode | null): readonly MLASTNodeTreeItem[];
-    /**
-     * Builds a `<ul>` or `<ol>` element. Adds a `start` attribute when the
-     * ordered list begins at a number other than 1.
-     *
-     * @param originNode - The mdast `list` node.
-     * @param token - The source token covering the list.
-     * @param depth - Current nesting depth.
-     * @param parentNode - Parent AST node, or `null` for top-level.
-     * @returns The list element node and its descendants.
-     */
     protected visitListElement(originNode: List, token: Token, depth: number, parentNode: MLASTParentNode | null): readonly MLASTNodeTreeItem[];
-    /**
-     * Builds a `<code>` element for inline code spans (backtick-delimited).
-     *
-     * @param originNode - The mdast `inlineCode` node.
-     * @param token - The source token covering the code span.
-     * @param offset - Start offset in the original source.
-     * @param endOffset - End offset in the original source.
-     * @param depth - Current nesting depth.
-     * @param parentNode - Parent AST node, or `null` for top-level.
-     * @returns The `<code>` element node (with a text child when content is found).
-     */
     protected visitInlineCode(originNode: InlineCode, token: Token, offset: number, endOffset: number, depth: number, parentNode: MLASTParentNode | null): readonly MLASTNodeTreeItem[];
-    /**
-     * Builds a `<pre><code>` structure for fenced code blocks.
-     * When a language is specified, adds `class="language-{lang}"` to the `<code>` element.
-     *
-     * @param originNode - The mdast `code` node.
-     * @param token - The source token covering the fenced block.
-     * @param depth - Current nesting depth.
-     * @param parentNode - Parent AST node, or `null` for top-level.
-     * @returns The `<pre>` and `<code>` element nodes.
-     */
     protected visitCodeBlock(originNode: Code, token: Token, depth: number, parentNode: MLASTParentNode | null): readonly MLASTNodeTreeItem[];
-    /**
-     * Builds a `<table>` element from a GFM table node.
-     * Marks the first row's offset as a header row so that its cells become `<th>`.
-     *
-     * @param originNode - The mdast `table` node (GFM extension).
-     * @param token - The source token covering the table.
-     * @param depth - Current nesting depth.
-     * @param parentNode - Parent AST node, or `null` for top-level.
-     * @returns The `<table>` element node and its descendants.
-     */
     protected visitTableElement(originNode: Table, token: Token, depth: number, parentNode: MLASTParentNode | null): readonly MLASTNodeTreeItem[];
     /**
-     * Dispatches a single mdast node to the appropriate visit method.
-     *
-     * @param originNode - The mdast node to convert.
-     * @param token - The source token covering the node's range.
-     * @param offset - Start offset in the original source.
-     * @param endOffset - End offset in the original source.
-     * @param depth - Current nesting depth.
-     * @param parentNode - Parent AST node, or `null` for top-level nodes.
-     * @returns An array of AST nodes for recognized Markdown constructs,
-     *   or `null` when the node type is not handled here (the caller is
-     *   responsible for handling it — typically `text`, `html`, or
-     *   parser-specific node types).
+     * Returns `null` when the node type is not handled here, signalling that
+     * the caller must handle it (typically `text`, `html`, or parser-specific
+     * node types).
      */
     protected nodeizeMarkdownNode(originNode: MdastNode, token: Token, offset: number, endOffset: number, depth: number, parentNode: MLASTParentNode | null): readonly MLASTNodeTreeItem[] | null;
     /**
-     * Extracts definition nodes from mdast children and populates `this.definitions`.
-     *
      * Per CommonMark spec, the first definition for a given identifier takes
      * precedence. remark-parse emits all definition nodes in source order, so
      * we skip duplicates via `Map.has` to honour the first-wins rule.
-     *
-     * @param children - The root-level mdast children to scan for `definition` nodes.
      */
     protected collectDefinitions(children: readonly RootContent[]): void;
 }
 /**
- * Computes the 1-based line number and 1-based column for a given offset.
- *
  * Equivalent to `getPosition()` in `@markuplint/parser-utils`, but that
  * function is not exported from the package. Kept as a standalone utility
  * to avoid coupling to parser-utils internals.
- *
- * @param source - The full source string.
- * @param offset - The 0-based character offset to resolve.
- * @returns An object with 1-based `line` and `col` values.
  */
 export declare function getLineAndColumn(source: string, offset: number): {
     line: number;

package/lib/markdown-aware-parser.js

@@ -1,34 +1,21 @@
 import { Parser, getNamespace } from '@markuplint/parser-utils';
 /**
- * Abstract base class for parsers that handle Markdown content.
- *
- * Provides shared logic for converting mdast nodes (headings, links, images,
- * lists, code, tables, etc.) into markuplint's AST. Both MarkdownParser and
- * MDXParser extend this class to avoid code duplication.
+ * Extends `Parser<MdastNode>` rather than `HtmlParser`: an earlier design
+ * extended `HtmlParser` and treated Markdown as opaque psblock nodes, which
+ * left Markdown constructs invisible to rules. Converting them to their HTML
+ * equivalents (with synthesized attributes such as `src`/`alt` from
+ * `![alt](src)`) is what makes Markdown content lintable.
  */
 export class MarkdownAwareParser extends Parser {
-    /**
-     * Stores link/image reference definitions (`[id]: url "title"`)
-     * extracted during tokenization for resolving linkReference/imageReference nodes.
-     */
     definitions = new Map();
-    /**
-     * Offsets of table rows that are header rows (first row of each table).
-     * Set by visitTableElement, read by nodeizeMarkdownNode for tableRow dispatch.
-     */
+    /** Set by visitTableElement, read by nodeizeMarkdownNode for tableRow dispatch. */
     #headerRowOffsets = new Set();
-    /**
-     * Current cell element name ('th' or 'td').
-     * Set by tableRow processing, read by tableCell processing.
-     * Reset to 'td' after each row.
-     */
+    /** Set by tableRow processing, read by tableCell processing; reset to 'td' after each row. */
     #currentCellName = 'td';
     constructor(options) {
         super(options);
     }
     /**
-     * Resets mutable state accumulated during a previous `parse()` call.
-     *
      * Must be called at the beginning of every `tokenize()` invocation to
      * prevent definitions, header-row offsets, and cell-name state from
      * leaking across successive `parse()` calls on the same parser instance.
@@ -39,13 +26,8 @@ export class MarkdownAwareParser extends Parser {
         this.#currentCellName = 'td';
     }
     /**
-     * Adjusts the flattened node list for Markdown output.
-     *
      * Disables whitespace and invalid-node exposure because Markdown
      * generates only synthetic elements with no real HTML whitespace tokens.
-     *
-     * @param nodeList - The flattened node tree produced by the base class.
-     * @returns The adjusted node list.
      */
     afterFlattenNodes(nodeList) {
         return super.afterFlattenNodes(nodeList, {
@@ -54,15 +36,8 @@ export class MarkdownAwareParser extends Parser {
         });
     }
     /**
-     * Creates a synthetic HTML attribute token for Markdown-derived elements.
-     *
      * The attribute positions point to the element's own token range because
      * Markdown syntax does not have discrete attribute source positions.
-     *
-     * @param name - The attribute name (e.g., `"href"`, `"alt"`).
-     * @param value - The attribute value extracted from Markdown syntax.
-     * @param token - The source token whose position is reused for the attribute.
-     * @returns A fully-formed HTML attribute node.
      */
     createSyntheticAttr(name, value, token) {
         const emptyToken = this.createToken('', token.offset, token.line, token.col);
@@ -84,17 +59,6 @@ export class MarkdownAwareParser extends Parser {
             isDuplicatable: false,
         };
     }
-    /**
-     * Builds a generic HTML element node from a Markdown construct.
-     *
-     * @param token - The source token covering the entire construct.
-     * @param nodeName - The HTML element name (e.g., `"p"`, `"h1"`, `"li"`).
-     * @param childNodes - The mdast children to recurse into.
-     * @param depth - Current nesting depth in the AST.
-     * @param parentNode - Parent AST node, or `null` for top-level nodes.
-     * @param attributes - Optional pre-built attributes to attach.
-     * @returns The element node followed by its descendants.
-     */
     visitMarkdownElement(token, nodeName, 
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     childNodes, depth, parentNode, attributes = []) {
@@ -122,15 +86,6 @@ export class MarkdownAwareParser extends Parser {
         const siblings = this.visitChildren([...childNodes], startTag);
         return [startTag, ...siblings];
     }
-    /**
-     * Builds an `<a>` element with `href` (and optionally `title`) attributes.
-     *
-     * @param originNode - The mdast `link` node.
-     * @param token - The source token covering the link.
-     * @param depth - Current nesting depth.
-     * @param parentNode - Parent AST node, or `null` for top-level.
-     * @returns The `<a>` element node and its descendants.
-     */
     visitLinkElement(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     originNode, token, depth, parentNode) {
@@ -140,15 +95,6 @@ export class MarkdownAwareParser extends Parser {
         }
         return this.visitMarkdownElement(token, 'a', originNode.children, depth, parentNode, attrs);
     }
-    /**
-     * Builds an `<img>` element with `src`, `alt`, and optionally `title` attributes.
-     *
-     * @param originNode - The mdast `image` node.
-     * @param token - The source token covering the image.
-     * @param depth - Current nesting depth.
-     * @param parentNode - Parent AST node, or `null` for top-level.
-     * @returns The `<img>` element node.
-     */
     visitImageElement(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     originNode, token, depth, parentNode) {
@@ -161,16 +107,6 @@ export class MarkdownAwareParser extends Parser {
         }
         return this.visitMarkdownElement(token, 'img', [], depth, parentNode, attrs);
     }
-    /**
-     * Builds a `<ul>` or `<ol>` element. Adds a `start` attribute when the
-     * ordered list begins at a number other than 1.
-     *
-     * @param originNode - The mdast `list` node.
-     * @param token - The source token covering the list.
-     * @param depth - Current nesting depth.
-     * @param parentNode - Parent AST node, or `null` for top-level.
-     * @returns The list element node and its descendants.
-     */
     visitListElement(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     originNode, token, depth, parentNode) {
@@ -181,17 +117,6 @@ export class MarkdownAwareParser extends Parser {
         }
         return this.visitMarkdownElement(token, nodeName, originNode.children, depth, parentNode, attrs);
     }
-    /**
-     * Builds a `<code>` element for inline code spans (backtick-delimited).
-     *
-     * @param originNode - The mdast `inlineCode` node.
-     * @param token - The source token covering the code span.
-     * @param offset - Start offset in the original source.
-     * @param endOffset - End offset in the original source.
-     * @param depth - Current nesting depth.
-     * @param parentNode - Parent AST node, or `null` for top-level.
-     * @returns The `<code>` element node (with a text child when content is found).
-     */
     visitInlineCode(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     originNode, token, offset, endOffset, depth, parentNode) {
@@ -236,20 +161,9 @@ export class MarkdownAwareParser extends Parser {
         this.appendChild(startTag, textNode);
         return [startTag];
     }
-    /**
-     * Builds a `<pre><code>` structure for fenced code blocks.
-     * When a language is specified, adds `class="language-{lang}"` to the `<code>` element.
-     *
-     * @param originNode - The mdast `code` node.
-     * @param token - The source token covering the fenced block.
-     * @param depth - Current nesting depth.
-     * @param parentNode - Parent AST node, or `null` for top-level.
-     * @returns The `<pre>` and `<code>` element nodes.
-     */
     visitCodeBlock(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     originNode, token, depth, parentNode) {
-        // Build <pre> element
         const preTag = {
             ...token,
             ...this.createToken(token),
@@ -270,7 +184,6 @@ export class MarkdownAwareParser extends Parser {
             isFragment: false,
             nodeName: 'pre',
         };
-        // Build <code> element as child of <pre>
         const codeAttrs = [];
         if (originNode.lang) {
             codeAttrs.push(this.createSyntheticAttr('class', `language-${originNode.lang}`, token));
@@ -295,7 +208,6 @@ export class MarkdownAwareParser extends Parser {
             isFragment: false,
             nodeName: 'code',
         };
-        // Add code content as text node if present
         if (originNode.value.length > 0) {
             const position = originNode.position;
             if (position) {
@@ -321,16 +233,6 @@ export class MarkdownAwareParser extends Parser {
         this.appendChild(preTag, codeTag);
         return [preTag, codeTag];
     }
-    /**
-     * Builds a `<table>` element from a GFM table node.
-     * Marks the first row's offset as a header row so that its cells become `<th>`.
-     *
-     * @param originNode - The mdast `table` node (GFM extension).
-     * @param token - The source token covering the table.
-     * @param depth - Current nesting depth.
-     * @param parentNode - Parent AST node, or `null` for top-level.
-     * @returns The `<table>` element node and its descendants.
-     */
     visitTableElement(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     originNode, token, depth, parentNode) {
@@ -341,18 +243,9 @@ export class MarkdownAwareParser extends Parser {
         return this.visitMarkdownElement(token, 'table', originNode.children, depth, parentNode);
     }
     /**
-     * Dispatches a single mdast node to the appropriate visit method.
-     *
-     * @param originNode - The mdast node to convert.
-     * @param token - The source token covering the node's range.
-     * @param offset - Start offset in the original source.
-     * @param endOffset - End offset in the original source.
-     * @param depth - Current nesting depth.
-     * @param parentNode - Parent AST node, or `null` for top-level nodes.
-     * @returns An array of AST nodes for recognized Markdown constructs,
-     *   or `null` when the node type is not handled here (the caller is
-     *   responsible for handling it — typically `text`, `html`, or
-     *   parser-specific node types).
+     * Returns `null` when the node type is not handled here, signalling that
+     * the caller must handle it (typically `text`, `html`, or parser-specific
+     * node types).
      */
     nodeizeMarkdownNode(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -384,6 +277,8 @@ export class MarkdownAwareParser extends Parser {
                 return this.visitMarkdownElement(token, 'li', originNode.children, depth, parentNode);
             }
             case 'blockquote': {
+                // Markdown's `> quote` syntax has no equivalent of the HTML
+                // `cite` attribute, so no `cite` attribute is synthesized.
                 return this.visitMarkdownElement(token, 'blockquote', originNode.children, depth, parentNode);
             }
             case 'thematicBreak': {
@@ -446,8 +341,9 @@ export class MarkdownAwareParser extends Parser {
         }
     }
     /**
-     * Resolves a linkReference using collected definitions, producing an `<a>` element.
-     * Falls back to a psblock when the definition is not found.
+     * Note: remark-parse resolves references at parse time when definitions
+     * exist, so unresolved references typically appear as plain text rather
+     * than `linkReference` nodes; the psblock fallback is a defensive path.
      */
     #visitLinkReference(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -469,8 +365,8 @@ export class MarkdownAwareParser extends Parser {
         return this.visitMarkdownElement(token, 'a', originNode.children, depth, parentNode, attrs);
     }
     /**
-     * Resolves an imageReference using collected definitions, producing an `<img>` element.
-     * Falls back to a psblock when the definition is not found.
+     * Note: as with linkReference, unresolved references typically appear as
+     * plain text in the mdast, so the psblock fallback is a defensive path.
      */
     #visitImageReference(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -495,13 +391,9 @@ export class MarkdownAwareParser extends Parser {
         return this.visitMarkdownElement(token, 'img', [], depth, parentNode, attrs);
     }
     /**
-     * Extracts definition nodes from mdast children and populates `this.definitions`.
-     *
      * Per CommonMark spec, the first definition for a given identifier takes
      * precedence. remark-parse emits all definition nodes in source order, so
      * we skip duplicates via `Map.has` to honour the first-wins rule.
-     *
-     * @param children - The root-level mdast children to scan for `definition` nodes.
      */
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     collectDefinitions(children) {
@@ -513,15 +405,9 @@ export class MarkdownAwareParser extends Parser {
     }
 }
 /**
- * Computes the 1-based line number and 1-based column for a given offset.
- *
  * Equivalent to `getPosition()` in `@markuplint/parser-utils`, but that
  * function is not exported from the package. Kept as a standalone utility
  * to avoid coupling to parser-utils internals.
- *
- * @param source - The full source string.
- * @param offset - The 0-based character offset to resolve.
- * @returns An object with 1-based `line` and `col` values.
  */
 export function getLineAndColumn(source, offset) {
     let line = 1;

package/lib/parser.d.ts

@@ -8,6 +8,12 @@ type MdastNode = RootContent;
  * Uses remark-parse to produce an mdast, then maps Markdown constructs
  * (headings, paragraphs, lists, links, etc.) to their corresponding HTML
  * element AST nodes. Raw HTML regions are parsed via HtmlParser.
+ *
+ * remark-parse (the unified ecosystem's de facto standard) was chosen over
+ * `@mdx-js/mdx`, which wraps remark-parse internally and adds about 24
+ * unnecessary dependencies for JS compilation that linting does not need,
+ * and over driving the lower-level tokenizer directly, which would require
+ * hand-building the mdast conversion with no practical benefit.
  */
 declare class MarkdownParser extends MarkdownAwareParser {
     #private;

package/lib/parser.js

@@ -10,6 +10,12 @@ import { MarkdownAwareParser, getLineAndColumn } from './markdown-aware-parser.j
  * Uses remark-parse to produce an mdast, then maps Markdown constructs
  * (headings, paragraphs, lists, links, etc.) to their corresponding HTML
  * element AST nodes. Raw HTML regions are parsed via HtmlParser.
+ *
+ * remark-parse (the unified ecosystem's de facto standard) was chosen over
+ * `@mdx-js/mdx`, which wraps remark-parse internally and adds about 24
+ * unnecessary dependencies for JS compilation that linting does not need,
+ * and over driving the lower-level tokenizer directly, which would require
+ * hand-building the mdast conversion with no practical benefit.
  */
 class MarkdownParser extends MarkdownAwareParser {
     #htmlParser = new HtmlParser();
@@ -84,7 +90,20 @@ class MarkdownParser extends MarkdownAwareParser {
             offsetOffset: offset,
             offsetLine: line,
             offsetColumn: col,
+            // HTML embedded inside Markdown is always a partial — never a
+            // full document — so force fragment parsing to keep parse5 from
+            // emitting `missing-doctype` / `misplaced-doctype` on every
+            // inline HTML block. Users cannot meaningfully override this
+            // because there is no Markdown construct that wraps a complete
+            // HTML document.
+            documentMode: 'fragment',
         });
+        // Surface tokenizer-level parse errors (e.g. `duplicate-attribute`)
+        // collected by the embedded HtmlParser. Without this, every parse
+        // error inside an inline HTML block would be silently dropped on
+        // the way back from `#htmlParser.parse()` even though the user has
+        // opted in via `severity.parseError`.
+        this.accumulateParseErrors(doc.parseErrors);
         return [...doc.nodeList];
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/markdown-parser",
-	"version": "5.0.0-rc.2",
+	"version": "5.0.0-rc.5",
 	"description": "Markdown parser for markuplint",
 	"repository": {
 		"type": "git",
@@ -10,7 +10,7 @@
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
 	"license": "MIT",
 	"engines": {
-		"node": ">=22"
+		"node": ">=24"
 	},
 	"type": "module",
 	"exports": {
@@ -28,9 +28,9 @@
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/html-parser": "5.0.0-rc.2",
-		"@markuplint/ml-ast": "5.0.0-rc.2",
-		"@markuplint/parser-utils": "5.0.0-rc.2",
+		"@markuplint/html-parser": "5.0.0-rc.5",
+		"@markuplint/ml-ast": "5.0.0-rc.5",
+		"@markuplint/parser-utils": "5.0.0-rc.5",
 		"remark-frontmatter": "5.0.0",
 		"remark-gfm": "4.0.1",
 		"remark-parse": "11.0.0",
@@ -39,5 +39,5 @@
 	"devDependencies": {
 		"@types/mdast": "4.0.4"
 	},
-	"gitHead": "e43763858d9234c417053becc73dbd088c1e7ea6"
+	"gitHead": "8d87463af2ff3f1b83fb28da20f1819362cf3555"
 }

package/src/index.spec.ts

@@ -751,6 +751,31 @@ describe('MarkdownParser', () => {
 	});
 });
 
+describe('Embedded HTML — parseErrors propagation (#3844)', () => {
+	test('emits tokenizer-level parse5 events for malformed embedded HTML', () => {
+		// `<div a a>` triggers parse5 `duplicate-attribute`. Even though the
+		// HTML lives inside Markdown, the tokenizer-level error must surface
+		// on `MLASTDocument.parseErrors`.
+		const doc = parse('# heading\n\n<div a a></div>\n');
+		const codes = (doc.parseErrors ?? []).map(e => e.code);
+		expect(codes).toContain('duplicate-attribute');
+	});
+
+	test('forces fragment parsing so document-level parse5 events do NOT leak from embedded HTML', () => {
+		// Without `documentMode: 'fragment'` forcing, a bare `<head>` in an
+		// inline HTML block would trip parse5's `missing-doctype` (since the
+		// internal HtmlParser would auto-detect document mode and complain
+		// about the missing `<!doctype html>`). Forcing fragment mode in
+		// `markdown-parser` is what prevents that leak — this test pins that
+		// contract.
+		const doc = parse('# heading\n\n<head><meta charset="utf-8"></head>\n');
+		const codes = (doc.parseErrors ?? []).map(e => e.code);
+		expect(codes).not.toContain('missing-doctype');
+		expect(codes).not.toContain('misplaced-doctype');
+		expect(codes).not.toContain('non-conforming-doctype');
+	});
+});
+
 describe('getLineAndColumn', () => {
 	test('returns line 1, col 1 for offset 0', () => {
 		expect(getLineAndColumn('hello', 0)).toStrictEqual({ line: 1, col: 1 });