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

npm install markdown-parser

package ↗

INSTALL

IMPORT

SIG · MARKDOWN-PARSER

markdown-parser

serializationjavascriptv0.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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.

MarkdownParser

✓ import { MarkdownParser } from 'markdown-parser';

✗ const { MarkdownParser } = require('markdown-parser');

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.

BlockNode

✓ import type { BlockNode } 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.

InlineNode

✓ import type { InlineNode } 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.

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 issues

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.

fix

To ensure all link references are correctly resolved, always feed all definition-containing chunks to the parser. Crucially, call `parser.parse('', { stream: false })` as the final step when all input has been provided to explicitly finalize the stream and allow the parser to resolve any remaining references. If displaying partial streams, handle potentially unresolved links gracefully in your rendering logic.

affects: >=0.1.1

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.

fix

It is strongly recommended to regularly consult the package's changelog or GitHub repository for any breaking changes before upgrading. For production environments, pinning to exact patch versions (`~0.1.x` or `0.1.x`) is advisable until a stable major release (v1.0.0) is available.

affects: >=0.1.1

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.

fix

For each distinct Markdown document or stream, instantiate a new `MarkdownParser`. Reusing an instance for unrelated content after a streaming parse without full finalization can lead to corrupted ASTs due to lingering internal state.

affects: >=0.1.1

Errors

Common errors & fixes

ReferenceError: require is not defined

Attempting to use the CommonJS `require()` syntax to import `markdown-parser` in an environment configured for ES modules (e.g., a Node.js project with `"type": "module"` in `package.json` or direct execution of `.mjs` files).

fix

Switch to ES module `import` syntax: `import { MarkdownParser } from 'markdown-parser';`.

Some expected Markdown blocks are missing from the output when using streaming mode.

When `stream: true` is enabled, the parser only emits blocks that have been fully closed and are stable. If the input ends prematurely or the stream is not explicitly finalized, any incomplete or buffered blocks will not be returned.

fix

After providing all available input chunks, make a final call to `parser.parse('', { stream: false })` to force the parser to finalize and emit any remaining buffered blocks. This signals the end of the stream.

TypeError: parser.parse is not a function

This error typically occurs when attempting to call the `parse` method directly on the imported module object rather than on an instance of the `MarkdownParser` class.

fix

Ensure you correctly instantiate the parser class before calling its methods: `const parser = new MarkdownParser();` then `parser.parse(...)`.

Upgrade

Version history

0.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

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