stream-markdown-parser 0.0.1

package/README.md

@@ -0,0 +1,97 @@
+
+# stream-markdown-parser
+
+Lightweight, framework-agnostic Markdown parser implemented in TypeScript. It focuses on producing a typed, structured representation of Markdown content so you can render it in Vue, React, or any other environment.
+
+[![NPM version](https://img.shields.io/npm/v/stream-markdown-parser?color=a1b858&label=)](https://www.npmjs.com/package/stream-markdown-parser)
+[![中文版](https://img.shields.io/badge/docs-中文文档-blue)](README.zh-CN.md)
+[![NPM downloads](https://img.shields.io/npm/dm/stream-markdown-parser)](https://www.npmjs.com/package/stream-markdown-parser)
+[![Bundle size](https://img.shields.io/bundlephobia/minzip/stream-markdown-parser)](https://bundlephobia.com/package/stream-markdown-parser)
+[![License](https://img.shields.io/npm/l/stream-markdown-parser)](./LICENSE)
+
+## Highlights
+
+- Framework-agnostic: pure TypeScript, no runtime framework dependency
+- Typed output: full TypeScript definitions for the produced node tree
+- Extensible: built on top of markdown-it and supports plugins (math, containers, etc.)
+- Optimized for streaming / large documents
+
+## Install
+
+```bash
+npm install stream-markdown-parser
+# or
+pnpm add stream-markdown-parser
+```
+
+## Quickstart
+
+```ts
+import { getMarkdown, parseMarkdownToStructure } from 'stream-markdown-parser'
+
+const md = getMarkdown()
+const nodes = parseMarkdownToStructure('# Hello World', md)
+console.log(nodes)
+```
+
+## Examples
+
+Basic parsing, math and custom container usage:
+
+```ts
+// basic
+const md = getMarkdown()
+parseMarkdownToStructure('# Title', md)
+
+// enable math
+const mdWithMath = getMarkdown({ enableMath: true })
+parseMarkdownToStructure('Inline $x^2$ and block math:\n$$x^2$$', mdWithMath)
+
+// enable custom containers
+const mdWithContainers = getMarkdown({ enableContainers: true })
+parseMarkdownToStructure('::: tip\nHi\n:::', mdWithContainers)
+```
+
+You can also process tokens directly:
+
+```ts
+import { processTokens } from 'stream-markdown-parser'
+import MarkdownIt from 'markdown-it'
+
+const md = new MarkdownIt()
+const tokens = md.parse('# Hello', {})
+const nodes = processTokens(tokens)
+```
+
+## API (overview)
+
+- getMarkdown(options?): returns a configured markdown-it instance
+- parseMarkdownToStructure(markdown, md, options?): parse a markdown string into typed nodes
+- processTokens(tokens): convert markdown-it tokens into typed nodes
+- parseInlineTokens(tokens): parse inline tokens
+
+See `src/types/index.ts` for the full `ParsedNode` definitions.
+
+## Integration
+
+- React / Vue / Vanilla: parse to nodes, then render with your components
+
+## Build & Dev
+
+This package is built using Vite and `vite-plugin-dts` for types generation. In this monorepo the package is under `packages/parser`.
+
+Build locally:
+
+```bash
+pnpm --filter ./packages/parser build
+```
+
+Typecheck:
+
+```bash
+pnpm --filter ./packages/parser -w -C . typecheck
+```
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,96 @@
+# stream-markdown-parser
+
+轻量化、框架无关的 Markdown 解析器，使用 TypeScript 编写。输出为强类型的节点树，方便在 Vue、React 或任何运行时中渲染。
+
+[![NPM version](https://img.shields.io/npm/v/stream-markdown-parser?color=a1b858&label=)](https://www.npmjs.com/package/stream-markdown-parser)
+[![English Docs](https://img.shields.io/badge/docs-English-blue)](README.md)
+[![NPM downloads](https://img.shields.io/npm/dm/stream-markdown-parser)](https://www.npmjs.com/package/stream-markdown-parser)
+[![Bundle size](https://img.shields.io/bundlephobia/minzip/stream-markdown-parser)](https://bundlephobia.com/package/stream-markdown-parser)
+[![License](https://img.shields.io/npm/l/stream-markdown-parser)](./LICENSE)
+
+## 主要特点
+
+- 框架无关：纯 TypeScript 实现，无运行时框架依赖
+- 强类型输出：包含完整的 TypeScript 类型定义
+- 可扩展：基于 markdown-it，支持插件（例如数学公式、容器等）
+- 适用于流式或大文档解析场景
+
+## 安装
+
+```bash
+pnpm add stream-markdown-parser
+# 或
+npm install stream-markdown-parser
+```
+
+## 快速开始
+
+```ts
+import { getMarkdown, parseMarkdownToStructure } from 'stream-markdown-parser'
+
+const md = getMarkdown()
+const nodes = parseMarkdownToStructure('# Hello World', md)
+console.log(nodes)
+```
+
+## 示例
+
+基本解析、数学公式与自定义容器：
+
+```ts
+// 基本用法
+const md = getMarkdown()
+parseMarkdownToStructure('# 标题', md)
+
+// 启用数学公式
+const mdWithMath = getMarkdown({ enableMath: true })
+parseMarkdownToStructure('行内 $x^2$ 与 块级公式:\n$$x^2$$', mdWithMath)
+
+// 启用自定义容器
+const mdWithContainers = getMarkdown({ enableContainers: true })
+parseMarkdownToStructure('::: tip\n提示内容\n:::', mdWithContainers)
+```
+
+也可以直接处理 markdown-it 的 tokens：
+
+```ts
+import MarkdownIt from 'markdown-it'
+import { processTokens } from 'stream-markdown-parser'
+
+const md = new MarkdownIt()
+const tokens = md.parse('# Hello', {})
+const nodes = processTokens(tokens)
+```
+
+## API 概览
+
+- `getMarkdown(options?)`：返回配置好的 `markdown-it` 实例
+- `parseMarkdownToStructure(markdown, md, options?)`：将 markdown 字符串解析为类型化节点
+- `processTokens(tokens)`：将 markdown-it tokens 转换为节点
+- `parseInlineTokens(tokens)`：解析内联 tokens
+
+完整的节点类型定义请查看 `src/types/index.ts`。
+
+## 与不同框架的集成
+
+解析出节点后，在 React / Vue / 或原生 JS 中用你的组件或渲染逻辑对节点进行渲染即可。
+
+## 构建与开发
+
+该包使用 Vite 构建，并通过 `vite-plugin-dts` 生成声明文件，在 monorepo 中位于 `packages/parser`。
+
+本地构建：
+
+```bash
+pnpm --filter ./packages/parser build
+```
+
+类型检查：
+
+```bash
+pnpm --filter ./packages/parser -w -C . typecheck
+```
+
+## 许可证
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,323 @@
+import { default as default_2 } from 'markdown-it';
+
+export declare interface AdmonitionNode extends BaseNode {
+    type: 'admonition';
+    kind: string;
+    title: string;
+    children: ParsedNode[];
+}
+
+export declare function applyContainers(md: default_2): void;
+
+export declare function applyMath(md: default_2, mathOpts?: MathOptions): void;
+
+export declare interface BaseNode {
+    type: string;
+    raw: string;
+    loading?: boolean;
+    code?: string;
+    diff?: boolean;
+}
+
+export declare interface BlockquoteNode extends BaseNode {
+    type: 'blockquote';
+    children: ParsedNode[];
+}
+
+export declare interface CheckboxInputNode extends BaseNode {
+    type: 'checkbox_input';
+    checked: boolean;
+}
+
+export declare interface CheckboxNode extends BaseNode {
+    type: 'checkbox';
+    checked: boolean;
+}
+
+export declare interface CodeBlockNode extends BaseNode {
+    type: 'code_block';
+    language: string;
+    code: string;
+    startLine?: number;
+    endLine?: number;
+    loading?: boolean;
+    diff?: boolean;
+    originalCode?: string;
+    updatedCode?: string;
+    raw: string;
+}
+
+export declare interface CustomComponents {
+    text: any;
+    paragraph: any;
+    heading: any;
+    code_block: any;
+    list: any;
+    blockquote: any;
+    table: any;
+    definition_list: any;
+    footnote: any;
+    footnote_reference: any;
+    admonition: any;
+    hardbreak: any;
+    link: any;
+    image: any;
+    thematic_break: any;
+    math_inline: any;
+    math_block: any;
+    strong: any;
+    emphasis: any;
+    strikethrough: any;
+    highlight: any;
+    insert: any;
+    subscript: any;
+    superscript: any;
+    emoji: any;
+    checkbox: any;
+    inline_code: any;
+    reference: any;
+    mermaid: any;
+    [key: string]: any;
+}
+
+export declare interface DefinitionItemNode extends BaseNode {
+    type: 'definition_item';
+    term: ParsedNode[];
+    definition: ParsedNode[];
+}
+
+export declare interface DefinitionListNode extends BaseNode {
+    type: 'definition_list';
+    items: DefinitionItemNode[];
+}
+
+export declare interface EmojiNode extends BaseNode {
+    type: 'emoji';
+    name: string;
+    markup: string;
+}
+
+export declare interface EmphasisNode extends BaseNode {
+    type: 'emphasis';
+    children: ParsedNode[];
+}
+
+export declare function findMatchingClose(src: string, startIdx: number, open: string, close: string): number;
+
+export declare interface FootnoteNode extends BaseNode {
+    type: 'footnote';
+    id: string;
+    children: ParsedNode[];
+}
+
+export declare interface FootnoteReferenceNode extends BaseNode {
+    type: 'footnote_reference';
+    id: string;
+}
+
+export declare function getDefaultMathOptions(): MathOptions | undefined;
+
+export declare function getMarkdown(opts?: GetMarkdownOptions): default_2;
+
+export declare interface GetMarkdownOptions extends Record<string, any> {
+    markdownItOptions?: Record<string, any>;
+    enableMath?: boolean;
+    enableContainers?: boolean;
+    mathOptions?: {
+        commands?: string[];
+        escapeExclamation?: boolean;
+    };
+}
+
+export declare interface HardBreakNode extends BaseNode {
+    type: 'hardbreak';
+}
+
+export declare interface HeadingNode extends BaseNode {
+    type: 'heading';
+    level: number;
+    text: string;
+    children: ParsedNode[];
+}
+
+export declare interface HighlightNode extends BaseNode {
+    type: 'highlight';
+    children: ParsedNode[];
+}
+
+export declare interface ImageNode extends BaseNode {
+    type: 'image';
+    src: string;
+    alt: string;
+    title: string | null;
+}
+
+export declare interface InlineCodeNode extends BaseNode {
+    type: 'inline_code';
+    code: string;
+}
+
+export declare interface InsertNode extends BaseNode {
+    type: 'insert';
+    children: ParsedNode[];
+}
+
+export declare const KATEX_COMMANDS: string[];
+
+export declare interface LinkNode extends BaseNode {
+    type: 'link';
+    href: string;
+    title: string | null;
+    text: string;
+    children: ParsedNode[];
+}
+
+export declare interface ListItemNode extends BaseNode {
+    type: 'list_item';
+    children: ParsedNode[];
+}
+
+export declare interface ListNode extends BaseNode {
+    type: 'list';
+    ordered: boolean;
+    start?: number;
+    items: ListItemNode[];
+}
+
+export declare type MarkdownRender = {
+    content: string;
+    nodes?: undefined;
+} | {
+    content?: undefined;
+    nodes: BaseNode[];
+};
+
+export declare interface MarkdownToken {
+    type: string;
+    tag?: string;
+    content?: string;
+    info?: string;
+    loading?: boolean;
+    children?: MarkdownToken[];
+    attrs?: [string, string][];
+    markup?: string;
+    meta?: any;
+    map?: [number, number];
+    raw?: string;
+}
+
+export declare interface MathBlockNode extends BaseNode {
+    type: 'math_block';
+    content: string;
+}
+
+export declare interface MathInlineNode extends BaseNode {
+    type: 'math_inline';
+    content: string;
+}
+
+/**
+ * MathOptions control how the math plugin normalizes content before
+ * handing it to KaTeX (or other math renderers).
+ *
+ * - commands: list of command words that should be auto-prefixed with a
+ *   backslash if not already escaped (e.g. 'infty' -> '\\infty'). Use a
+ *   conservative list to avoid false positives in prose.
+ * - escapeExclamation: whether to escape standalone '!' to '\\!' (default true).
+ */
+export declare interface MathOptions {
+    /** List of command words to auto-escape. */
+    commands?: readonly string[];
+    /** Whether to escape standalone '!' (default: true). */
+    escapeExclamation?: boolean;
+}
+
+export declare interface MermaidBlockNode {
+    node: {
+        type: 'code_block';
+        language: string;
+        code: string;
+        loading?: boolean;
+    };
+}
+
+export declare function normalizeStandaloneBackslashT(s: string, opts?: MathOptions): string;
+
+export declare interface ParagraphNode extends BaseNode {
+    type: 'paragraph';
+    children: ParsedNode[];
+    maybeCheckbox?: boolean;
+}
+
+export declare type ParsedNode = TextNode | HeadingNode | ParagraphNode | ListNode | ListItemNode | CodeBlockNode | InlineCodeNode | LinkNode | ImageNode | ThematicBreakNode | BlockquoteNode | TableNode | TableRowNode | TableCellNode | StrongNode | EmphasisNode | StrikethroughNode | HighlightNode | InsertNode | SubscriptNode | SuperscriptNode | CheckboxNode | CheckboxInputNode | EmojiNode | DefinitionListNode | DefinitionItemNode | FootnoteNode | FootnoteReferenceNode | AdmonitionNode | HardBreakNode | MathInlineNode | MathBlockNode | ReferenceNode | Record<string, any>;
+
+export declare function parseInlineTokens(tokens: MarkdownToken[], raw?: string, pPreToken?: MarkdownToken): ParsedNode[];
+
+export declare function parseMarkdownToStructure(markdown: string, md: default_2, options?: ParseOptions): ParsedNode[];
+
+export declare interface ParseOptions {
+    preTransformTokens?: TransformTokensHook;
+    postTransformTokens?: TransformTokensHook;
+}
+
+export declare type PostTransformNodesHook = (nodes: ParsedNode[]) => ParsedNode[];
+
+export declare function processTokens(tokens: MarkdownToken[]): ParsedNode[];
+
+export declare interface ReferenceNode extends BaseNode {
+    type: 'reference';
+    id: string;
+}
+
+export declare function setDefaultMathOptions(opts: MathOptions | undefined): void;
+
+export declare interface StrikethroughNode extends BaseNode {
+    type: 'strikethrough';
+    children: ParsedNode[];
+}
+
+export declare interface StrongNode extends BaseNode {
+    type: 'strong';
+    children: ParsedNode[];
+}
+
+export declare interface SubscriptNode extends BaseNode {
+    type: 'subscript';
+    children: ParsedNode[];
+}
+
+export declare interface SuperscriptNode extends BaseNode {
+    type: 'superscript';
+    children: ParsedNode[];
+}
+
+export declare interface TableCellNode extends BaseNode {
+    type: 'table_cell';
+    header: boolean;
+    children: ParsedNode[];
+}
+
+export declare interface TableNode extends BaseNode {
+    type: 'table';
+    header: TableRowNode;
+    rows: TableRowNode[];
+}
+
+export declare interface TableRowNode extends BaseNode {
+    type: 'table_row';
+    cells: TableCellNode[];
+}
+
+export declare interface TextNode extends BaseNode {
+    type: 'text';
+    content: string;
+    center?: boolean;
+}
+
+export declare interface ThematicBreakNode extends BaseNode {
+    type: 'thematic_break';
+}
+
+export declare type TransformTokensHook = (tokens: MarkdownToken[]) => MarkdownToken[];
+
+export { }