Registry / serialization / markdown-parser

markdown-parser

library0.1.1jsnpmunverified

The `markdown-parser` library provides a robust and fully typed parser for Markdown content, adhering strictly to the CommonMark specification and including full support for GitHub Flavored Markdown (GFM) tables. Currently at version 0.1.1, its primary differentiation is its advanced streaming and incremental parsing capabilities, which are especially critical for applications consuming continuously arriving content, such as outputs from large language models or real-time communication systems. Unlike conventional Markdown parsers that necessitate complete input before generating an Abstract Syntax Tree (AST), `markdown-parser` can process text in chunks, emitting finalized block nodes as they become stable while internally managing the state of incomplete structures. This design allows for immediate display and dynamic manipulation of Markdown content without waiting for the entire stream to conclude. The library is engineered to produce a structured, typed AST, making it highly amenable to programmatic interaction, rendering, and analysis. While a formal release cadence is not explicitly stated, the early version number suggests active and iterative development.

serialization

package ↗

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

This package targets Node.js >=18 and is primarily designed for ES module (ESM) usage. While CommonJS might technically work via transpilation or bundlers, native ESM imports are the recommended and intended way to consume this library.

import { MarkdownParser } from 'markdown-parser';

The `BlockNode` type represents a parsed block-level Markdown element (e.g., heading, paragraph, list). Importing this type is useful for type-checking and understanding the structure of the AST returned by the parser.

import type { BlockNode } from 'markdown-parser';

The `InlineNode` type defines inline Markdown elements (e.g., text, emphasis, code span) which typically exist as children within `BlockNode` structures. Useful for detailed AST traversal.

import type { InlineNode } from 'markdown-parser';

This quickstart demonstrates both synchronous parsing of a complete Markdown string and the library's core feature: streaming/incremental parsing, where content is fed in chunks and finalized blocks are emitted progressively.

import { MarkdownParser } from "markdown-parser"; import type { BlockNode } from "markdown-parser"; const parser = new MarkdownParser(); // Example 1: Parse complete markdown in one go const completeNodes: BlockNode[] = parser.parse("# Hello World\nThis is a paragraph."); console.log('Complete Parse Output:', JSON.stringify(completeNodes, null, 2)); // Expected: [ // { type: "heading", level: 1, children: [{ type: "text", text: "Hello World" }] }, // { type: "paragraph", children: [{ type: "text", text: "This is a paragraph." }] } // ] // Example 2: Parse with streaming mode for incremental content console.log('\n--- Streaming Parse ---'); let streamOutput1: BlockNode[] = parser.parse("# Hello World\nThis", { stream: true }); console.log('Stream Part 1:', JSON.stringify(streamOutput1, null, 2)); // Expected: [ // { type: "heading", level: 1, children: [{ type: "text", text: "Hello World" }] } // ] (paragraph is still open) let streamOutput2: BlockNode[] = parser.parse(" is a paragraph\n\nThis is another paragraph.", { stream: true }); console.log('Stream Part 2:', JSON.stringify(streamOutput2, null, 2)); // Expected: [ // { type: "paragraph", children: [{ type: "text", text: "This is a paragraph." }] } // ] (second paragraph still open) let streamOutput3: BlockNode[] = parser.parse("", { stream: false }); // Finalize the stream console.log('Stream Finalize:', JSON.stringify(streamOutput3, null, 2)); // Expected: [ // { type: "paragraph", children: [{ type: "text", text: "This is another paragraph." }] } // ] console.log('\n--- End Streaming Parse ---');

Debug

Known footguns

gotchaWhen utilizing the streaming mode, it's crucial to understand that link reference definitions (e.g., `[label]: url`) might not resolve immediately if their corresponding definitions arrive in subsequent input chunks. The parser processes content sequentially, and any link references that precede their definitions will remain unresolved until the definitions are fed into the stream and the relevant blocks are finalized.

breakingAs this package is in its very early stages (v0.1.x), the API is considered unstable. Breaking changes, including alterations to node structures, parser options, or method signatures, are highly likely to occur in minor or even patch versions as the API matures towards a stable v1.0.0 release. Updates may require code adjustments.

gotchaThe parser's `parse` method maintains internal state when `stream: true` is used. This means that a single `MarkdownParser` instance should be used for a continuous stream of input. Starting a new, unrelated stream requires a new `MarkdownParser` instance or careful management of the state, though the latter is not directly exposed.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

9 hits · last 30 days

gptbot

ahrefsbot

script

Resources

packagehttps://www.npmjs.com/package/markdown-parser ↗