#@mizchi/markdown

#Features

• Fast: Edit-position based incremental updates inspired by CRDTs Go Brrr
• CommonMark compliant: passes all 652 examples of the CommonMark 0.31.2 spec
• Source-oriented CST: Retains node spans so byte-preserving tools can edit the original source
• Incremental parsing: Re-parses only changed blocks (up to 42x faster)
• GFM: GitHub Flavored Markdown support (tables, task lists, strikethrough)
• Cross-platform: Works on JS, WASM-GC, and native targets
• HTML rendering: Built-in HTML renderer with remark-html compatible output
• mdast compatible: AST follows mdast specification

#JavaScript API

npm install @mizchi/markdown

#Usage

import { parse, toHtml, toMarkdown } from "@mizchi/markdown";

// Parse to AST
const ast = parse("# Hello\n\n**Bold** text");
console.log(ast.children[0].type); // "heading"

// Convert to HTML
const html = toHtml("See https://example.com/docs\n");
// => '<p>See <a href="https://example.com/docs">https://example.com/docs</a></p>\n'

// Disable bare URL links when you need plain text output
const plain = toHtml("See https://example.com/docs\n", { autolink: false });
// => "<p>See https://example.com/docs</p>\n"

// Match CommonMark 0.31.2 rendering by disabling GFM renderer extensions
const commonmark = toHtml("<script>raw</script>\n\nhttps://example.com\n", {
  autolink: false,
  tagfilter: false,
});
// => "<script>raw</script>\n<p>https://example.com</p>\n"

// Normalize markdown
const normalized = toMarkdown("# Hello\n\n\n\nWorld");
// => "# Hello\n\nWorld\n"

#WebAssembly API

import { parse, toHtml, toMarkdown } from "@mizchi/markdown/wasm";

const ast = parse("# Hello");
const html = toHtml("See https://example.com/docs\n");
const markdown = toMarkdown("# Hello\n\n\nWorld");

#Cloudflare Workers

#Optional WikiLinks

import { parse, toHtml } from "@mizchi/markdown";

const ast = parse("[[MoonBit#syntax|MoonBit syntax]]", { wikilinks: true });
// ast.children[0].children[0].type === "wikiLink"

const html = toHtml("[[MoonBit|MoonBit notes]]", { wikilinks: true });
// => '<p><a href="MoonBit">MoonBit notes</a></p>\n'

#Extended syntax

> [!WARNING]
> Check this first.[^details]

$$
E = mc^2
$$

:::note Optional title
Markdown stays available inside the container.
:::

Use :badge[stable]{.green level=high}.

Term
: Definition

# Attributed heading
{#intro .wide}

[^details]: Footnote content.

#Incremental Parsing

import { createDocument, insertEdit } from "@mizchi/markdown";

// Create document handle
const doc = createDocument("# Hello");

// Access AST, HTML, or Markdown
console.log(doc.ast);        // Parsed AST
console.log(doc.toHtml());   // "<h1>Hello</h1>\n"
console.log(doc.toMarkdown()); // "# Hello\n"

// Incremental update (faster than full re-parse)
const edit = insertEdit(7, 6); // Insert 6 chars at position 7
const newDoc = doc.update("# Hello World", edit);

// Free resources when done
doc.dispose();
newDoc.dispose();

#TypeScript Support

import { parse, Document, Block, Inline } from "@mizchi/markdown";

const ast: Document = parse("# Hello");
const heading = ast.children[0] as HeadingBlock;
console.log(heading.level); // 1

#MoonBit API

#Installation

moon add mizchi/markdown

#Usage

// Parse markdown
let result = @markdown.parse("# Hello\n\nWorld")
let doc = result.document

// Serialize back to canonical, normalized Markdown
let output = @markdown.serialize(doc)

// Render to HTML
let html = @markdown.render_html(doc)

// Or use convenience function
let html = @markdown.md_to_html("# Hello\n\nWorld")
let linked = @markdown.md_to_html("See https://example.com/docs\n")
let plain = @markdown.md_to_html("See https://example.com/docs\n", autolink=false)

// Disable the GFM tagfilter when matching plain CommonMark raw-HTML output
let commonmark_html = @markdown.md_to_html("<script>raw</script>\n", tagfilter=false)

// Enable the WikiLink extension explicitly
let wiki_html = @markdown.md_to_html("[[MoonBit|MoonBit notes]]", wikilinks=true)

#Display-math renderer

let document = @markdown.parse("$$\nx^2\n$$\n").document
let options = @markdown.RenderOptions::default().with_math_block_renderer(
  fn(source) { render_with_katex(source) },
)
let html = @markdown.render_html_with_options(document, options)

#Native CLI

_build/native/release/build/cmd/mmmd-native/mmmd-native.exe --format html < document.md
_build/native/release/build/cmd/mmmd-native/mmmd-native.exe --format tui < document.md

#Incremental Parsing

// Initial parse
let result = @markdown.parse(source)
let doc = result.document

// Create edit info
let edit = @markdown.EditInfo::replace(
  change_start,    // Start position
  old_length,      // Length of replaced text
  new_length       // Length of new text
)

// Incremental update (reuses unchanged blocks)
let inc_result = @markdown.parse_incremental(doc, old_source, new_source, edit)
let new_doc = inc_result.document

#Typed MDX Declarations

import {
  "mizchi/markdown",
  "mizchi/markdown/x/mdx" @mdx,
}

let schema = @mdx.MdxSchema::closed([
  @mdx.ComponentSchema::new(
    "Fold",
    [
      @mdx.PropSchema::required("id", @mdx.MdxValueType::Text),
      @mdx.PropSchema::required(
        "kind",
        @mdx.MdxValueType::OneOf(["concept", "procedure"]),
      ),
      @mdx.PropSchema::optional("requires", @mdx.MdxValueType::TextList),
    ],
  ),
])

let source = #|<Fold id="auth.mfa" kind="procedure" requires={["auth.login"]} />
let checked = @mdx.type_check_mdx(@markdown.parse(source).document, schema)
let is_valid = checked.is_valid()

#Playground

pnpm install
moon build --target js
pnpm exec vite

#Frontend Editor Package

pnpm add @mizchi/markdown @luna_ui/luna

import { SyntaxHighlightEditor } from "@mizchi/markdown/editor";
import "@mizchi/markdown/editor/style.css";

<SyntaxHighlightEditor
  value={() => markdown}
  onChange={(next) => setMarkdown(next)}
/>;

import { loadHighlighter } from "@mizchi/markdown/highlight";

const highlightMoonBit = await loadHighlighter("moonbit");
const html = highlightMoonBit?.("fn main { println(\"hi\") }");

#Performance

#Native CPU profiling

just profile-native parse 100
just profile-native render 200
just profile-native parse-render 100

just profile-js parse 50

#JavaScript Wasm SIMD via ESM Integration

just inline-wasm-build
just inline-wasm-check
just bench-js

#Documentation

#CommonMark Compatibility

#Credits

• Fonts: PlemolJP (SIL Open Font License 1.1) — bundled in playground/public/fonts/

#License