v2.0.11

Architecture

Last updated


NanoMD separates parsing from rendering into independent layers: parsing only produces data, while HTML output and dependency rendering are optional downstream steps.
Other JavaScript Markdown libraries cover adjacent ground: marked is a parser and compiler built for speed, markdown-it offers full CommonMark support with syntax plugins, markdown-exit is a TypeScript rewrite of markdown-it, showdown converts in both directions between Markdown and HTML, remark is a plugin-based processor in the unified collective, and micromark is a small CommonMark-compliant parser; each grows past core Markdown through plugins or extensions. NanoMD takes a different shape: one Parse() call returns an AST that serializes to JSON with json() and to escaped, sanitized HTML with html(), and Mermaid diagrams, KaTeX math and Chart.js charts are built-in syntax whose libraries load from a CDN only when Init() enables them.

System Overview


graph LR
    Input[Markdown text] --> Block[Block parsing ParseLines]
    Block --> Inline[Inline parsing ParseInline]
    Inline --> Post[Footnote and link-ref post-processing]
    Post --> AST[AST]
    AST --> JSON["AST.json() (build your own native renderer)"]
    AST --> HTML["AST.html()"]
    HTML --> DOM[.nanomd container]
    DOM --> Refresh["Refresh() dependency rendering"]
    Init["Init() loads dependencies"] --> Refresh
  1. graph LR
  2. Input[Markdown text] --> Block[Block parsing ParseLines]
  3. Block --> Inline[Inline parsing ParseInline]
  4. Inline --> Post[Footnote and link-ref post-processing]
  5. Post --> AST[AST]
  6. AST --> JSON["AST.json() (build your own native renderer)"]
  7. AST --> HTML["AST.html()"]
  8. HTML --> DOM[.nanomd container]
  9. DOM --> Refresh["Refresh() dependency rendering"]
  10. Init["Init() loads dependencies"] --> Refresh

Layers


LayerSourceResponsibilityNeeds DOM
Block parsingsrc/parser/index.ts, blockquote.ts, codeBlock.ts, heading.ts, list.ts, tableBlock.ts, footnote.tsClassifies each line and produces BlockNodesNo
Inline parsingsrc/parser/inline.ts, link.tsCode spans, math, links, styles and other inline nodesNo
Post-processingfootnote.ts, link.tsFootnote numbering and reference link resolutionNo
HTML outputsrc/parser/html.tsAST.html(), escaping and raw HTML sanitizationNo
Runtimesrc/parser/refresh.ts, Init() in index.tsLoads dependencies, renders charts, math and diagrams, binds copy buttons and file linksYes
Stylessrc/sass/parser.scss.nanomd container styles, compiled to parser.css—

Design Principles


PrincipleDescription
Data separate from renderingParse() returns only a node tree, and json() copies it out as plain data for renderers beyond the web
Single pass per lineEach line is classified once, so time grows linearly with document size
Escape at outputThe AST keeps the original text; html() escapes text and attributes
No automatic dependenciesMermaid, KaTeX, Chart.js and prettify load only when enabled in Init()
Fall back to codeBlocks keep showing as plain code when a dependency is missing or the syntax is invalid

See doc/architecture.md for the full module diagrams and Parsing Pipeline for the parse order.
  1. <script>
  2. const ast = MDParser.Parse("# Title\n\nText with **bold**.");
  3. console.log(ast.map((node) => node.type).join(" -> "));
  4. console.log(ast.html());
  5. </script>
Live preview · @pardnchiu/nanomd@2.0.11
中文