MarkdownParser

The main parser class for converting markdown text into structured AST nodes

MarkdownParser class

The MarkdownParser class is the core of the markdown-parser library. It parses markdown text into a structured Abstract Syntax Tree (AST) of block and inline nodes following the CommonMark specification.

Constructor

const parser = new MarkdownParser();

Creates a new parser instance. Each instance maintains its own internal state for reference definitions and parsing position.

parse()

Parses markdown input and returns an array of block nodes.

parse(input: string, options?: { stream?: boolean }): BlockNode[]

Parameters

input · string · required

The markdown text to parse

options · object

Optional configuration for the parser

Show properties

stream · boolean · default: "false"

Enable streaming mode. When true, the parser returns only finalized/closed nodes and maintains internal state for subsequent calls. When false, all remaining open blocks are finalized before returning.

Returns

BlockNode[] · array

An array of parsed block-level nodes. See Block Nodes for detailed node types.

Usage

Basic parsing

import { MarkdownParser } from 'markdown-parser';

const parser = new MarkdownParser();
const nodes = parser.parse('# Hello World\n\nThis is a paragraph.');

console.log(nodes);
// [
//   { type: 'heading', level: 1, children: [{ type: 'text', text: 'Hello World' }] },
//   { type: 'paragraph', children: [{ type: 'text', text: 'This is a paragraph.' }] }
// ]

Streaming mode

Streaming mode allows processing markdown incrementally as it arrives:

const parser = new MarkdownParser();

// First chunk
let nodes = parser.parse('# Heading\n\nFirst ', { stream: true });
console.log(nodes); // [{ type: 'heading', ... }]

// Second chunk - paragraph is still open
nodes = parser.parse('paragraph.\n\n', { stream: true });
console.log(nodes); // [{ type: 'paragraph', ... }]

// Final chunk - finalize remaining blocks
nodes = parser.parse('', { stream: false });
console.log(nodes); // Any remaining open blocks

Supported markdown features

The parser implements full CommonMark 0.31.2 specification including:

• Block elements: Headings (ATX and Setext), paragraphs, code blocks (fenced and indented), blockquotes, lists (ordered and unordered), tables (GFM extension), thematic breaks, HTML blocks
• Inline elements: Emphasis, strong emphasis, links (inline and reference), images, code spans, line breaks (hard and soft), HTML tags, autolinks
• Advanced features: Nested blockquotes, nested lists, reference link definitions, table alignment

Reference link definitions

The parser automatically extracts and processes reference link definitions:

const markdown = `
[example]: https://example.com "Example Site"

Check out [example] for more info.
`;

const nodes = parser.parse(markdown);
// Reference definitions are stored internally and used to resolve links

CommonMark compliance

This parser is fully compliant with CommonMark 0.31.2, ensuring consistent and predictable parsing behavior across different markdown implementations.