@lanexio/parser-grammar-markdown

This page documents @lanexio/parser-grammar-markdown, the Markdown grammar package implementing CommonMark 0.31.2 with GitHub Flavored Markdown (GFM) extensions: tables, task lists, strikethrough, autolinks, and more.

• Version: Stable
• Module name: parser-grammar-markdown
• Package: @lanexio/parser-grammar-markdown
• Import path: @lanexio/parser-grammar-markdown
• Layer: 2 (Grammar)
• Runtime: Universal (browser, server, edge worker)
• Module format: ESM
• Stability: Stable
• Primary use case: Parse CommonMark and GFM Markdown documents into a flat AST.

Layer contract

Layer 2 dependency rules

This package depends only on Layer 1 core packages. It does not import from query, bridge, devtools, or entry packages. Grammar packs never depend on other grammar packs.

When to use this module

• You need to parse Markdown documents (CommonMark or GFM) into a traversable AST.
• You need to serialize a parsed Markdown tree back to Markdown source (roundtrip).
• You want to extract text content or render Markdown to HTML.

Module boundary

Boundary	Description
Inputs	Uint8Array (source bytes) + optional ParseMarkdownOptions
Outputs	LexTree (flat AST rooted at MdKind.Document)
Side effects	Side-effect import ./embed.js registers fenced-code-block embeddings for CSS, JSON, HTML guest languages
Determinism	Yes (same bytes + same options produce identical tree)
External dependencies	@lanexio/parser-core
Never-throw guarantee	Yes for all parse entry points
Security surface	Serializer output emits raw Markdown source. renderMarkdownHtml emits raw HTML.

Installation

1. Install the package.

   pnpm

   pnpm add @lanexio/parser-grammar-markdown

   npm

   npm install @lanexio/parser-grammar-markdown

   yarn

   yarn add @lanexio/parser-grammar-markdown

2. Import the named export.

   import { parseMarkdown } from '@lanexio/parser-grammar-markdown';

Peer dependencies

Requirement	Required	Layer	Notes
@lanexio/parser-core	Yes	1	^1.0.0

Basic Usage

Headless usage (pure TypeScript)

import { parseMarkdown } from '@lanexio/parser-grammar-markdown';

const encoder = new TextEncoder();
const bytes = encoder.encode('# Hello\n\nA paragraph with **bold** text.');

const tree = parseMarkdown(bytes);

console.log(tree.nodeCount);   // total nodes in the flat AST
console.log(tree.root.kind);   // MdKind.Document

CommonMark-only mode

import { parseMarkdown } from '@lanexio/parser-grammar-markdown';

const encoder = new TextEncoder();
const tree = parseMarkdown(
  encoder.encode('# CommonMark only'),
  { gfm: false }
);

Serialize back to Markdown

import { parseMarkdown, serializeMarkdown } from '@lanexio/parser-grammar-markdown';

const encoder = new TextEncoder();
const tree = parseMarkdown(encoder.encode('# Hello\n\nA paragraph.'));
const markdown = serializeMarkdown(tree);
// "# Hello\n\nA paragraph.\n"

Exports

Export	Type	Description
parseMarkdown	(source: Uint8Array, options?: ParseMarkdownOptions) => LexTree	Parse Markdown. Never throws.
parseMarkdownWithScan	(source: Uint8Array, options?: ParseMarkdownOptions) => Promise<LexTree>	Parse Markdown with pre-computed structural scan. Async.
serializeMarkdown	(input: LexTree | LexNode) => string	Serialize tree back to Markdown source (roundtrip).
renderMarkdownHtml	(tree: LexTree, options?: RenderMarkdownHtmlOptions) => string	Render Markdown tree to HTML string.
textContent	(node: LexNode) => string	Extract plain text from a Markdown tree.
MdKind	const object	Numeric kind IDs for all Markdown node types.
MdField	const object	Numeric field IDs for Markdown element slots.
MD_FIELD_NAMES_BY_ID	readonly string[]	Field name lookup by numeric field ID.
MdParseErrorCode	const object	Parse error code constants.
MD_FLAG_HEADING_LEVEL_MASK	number	Bitmask for heading level in node flags.
MD_FLAG_HEADING_LEVEL_SHIFT	number	Bit shift for heading level in node flags.
MD_FLAG_LIST_LOOSE	number	Flag for loose list items.
mdEncodeHeadingLevel	(level: number) => number	Encode heading level into node flags.
mdHeadingLevel	(flags: number) => number	Decode heading level from node flags.
mdListIsLoose	(flags: number) => boolean	Check if a list node is loose.
markdownGrammar	LanexioParserPureGrammar	Grammar descriptor for use with parser-pure.
markdownRegistration	GrammarRegistration	Registration for the unified grammar registry.

Options

ParseMarkdownOptions

Field	Type	Required	Default	Description
gfm	boolean	No	true	Enable GFM extensions (tables, task lists, strikethrough, autolinks).
extendedAutolink	boolean	No	true (when gfm: true)	Enable GFM extended autolink detection (bare URLs, www. hosts, email).
useSimdScan	boolean	No	false	Use SIMD or scalar pre-scan for delimiter bytes during inline parsing.

RenderMarkdownHtmlOptions

Field	Type	Required	Default	Description
(reserved)	-	-	-	Reserved for future extension.

Return shape

Property	Type	Description
root	LexNode	Root node (MdKind.Document).
nodeCount	number	Total nodes in the tree.
source	Uint8Array	Original parsed bytes.

Exported types

Type	Purpose	Notes
ParseMarkdownOptions	Options for parseMarkdown	See options table above.
RenderMarkdownHtmlOptions	Options for renderMarkdownHtml	Reserved for future extension.
MdParseError	Parse error descriptor	Returned via error codes.

Configuration and Extension

GFM extensions

GFM extensions are enabled by default. This includes tables, task list items, strikethrough, autolinks, and extended autolinks. Pass { gfm: false } to restrict to strict CommonMark 0.31.2 only.

Fenced code block embeddings

Side-effect import ./embed.js registers known guest languages (CSS, JSON, HTML) for fenced code block embedding. When a fenced code block has an info string matching a registered language, the block content can be parsed as the guest language.

Accessibility

Accessibility requirements

The Markdown parser preserves the document outline (headings, lists) in the AST structure. Serialization output preserves semantic Markdown syntax. renderMarkdownHtml produces HTML that preserves semantic structure.

Accessibility checklist

Concern	Status
Generated output semantics	Preserves document structure (headings, lists, emphasis)
ARIA attributes in serialized output	Not applicable (Markdown source output)
Semantic element round-trip	Yes (parse.serialize.parse is structurally identical)

Security

Security considerations

• parseMarkdown never throws on any byte sequence.
• renderMarkdownHtml emits raw HTML — callers must sanitize before browser insertion.
• serializeMarkdown emits raw Markdown source, not HTML.

Threat	Mitigation	Status
Malformed input byte sequence	Panic-free guarantee: all inputs accepted, errors produce LexError AST nodes	Implemented
XSS via HTML renderer output	renderMarkdownHtml emits raw HTML — caller is responsible for safe insertion	Documented

Companion packages

Package	Relationship	Layer	Notes
@lanexio/parser-core	Requires	1	Provides LexTree, LexNode, LexCursor
@lanexio/parser-grammar-html	Dev dependency	2	Used for HTML embedding in fenced code blocks
@lanexio/parser-pure	Consumes	4	Wraps parseMarkdown in a unified bridge

Integration example

import { parseMarkdown, MdKind } from '@lanexio/parser-grammar-markdown';
import { LexQuery } from '@lanexio/parser-query';

const encoder = new TextEncoder();
const tree = parseMarkdown(encoder.encode('# Title\n\nA paragraph.\n\n- item one\n- item two'));

const resolver = (name: string) => (MdKind as Record<string, number | undefined>)[name];
const query = LexQuery.compile('Item', resolver);

for (const node of query.matches(tree)) {
  console.log(node.kind, node.range);
}

Changelog

Version	Date	Status	Notable changes
1.0.0	2026-05-29	Current	Initial stable release. Apache-2.0.

Migration notes

• None.

Related Content

Parsing Markdown Guide: parse Markdown with options, serialization, kind constants.

Markdown Conformance CommonMark and GFM test suite results.

Flat AST How the 16-byte node layout works and how to traverse it efficiently.

Stability Guarantees Never-throw, panic-free, and 3-token recovery.