Show HN: Quikdown – 17 KB bidirectional Markdown parser and rich-fence editor

Notifications You must be signed in to change notification settings

Fork 1

Star 11

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

125 Commits

125 Commits

.github

.github

.husky

.husky

bin

bin

changelog

changelog

dev

dev

dist

dist

docs

docs

downloads

downloads

edit

edit

examples

examples

exp-bd

exp-bd

frameworks

frameworks

pages

pages

site

site

src

src

test-results

test-results

tests

tests

tools

tools

.babelrc

.babelrc

.gitignore

.gitignore

.js

.js

.nojekyll

.nojekyll

.npmignore

.npmignore

BADGES.md

BADGES.md

CONTRIBUTING.md

CONTRIBUTING.md

LICENSE.txt

LICENSE.txt

MakeQuikdownRelease.md

MakeQuikdownRelease.md

OldREADME.md.old

OldREADME.md.old

README.md

README.md

agents.md

agents.md

eslint.config.js

eslint.config.js

favicon.svg

favicon.svg

index-old.html

index-old.html

index.html

index.html

llms.txt

llms.txt

package-lock.json

package-lock.json

package.json

package.json

playwright.config.cjs

playwright.config.cjs

qde.html

qde.html

quikdown-test.pdf

quikdown-test.pdf

robots.txt

robots.txt

rollup.config.coverage.js

rollup.config.coverage.js

rollup.config.js

rollup.config.js

rollup.config.standalone.js

rollup.config.standalone.js

sitemap.xml

sitemap.xml

Repository files navigation

Quikdown is a small, safe, bidirectional Markdown parser with a drop-in editor for browser and Node.js apps — with rich fenced-block rendering, Markdown ↔ HTML round-tripping, undo/redo, headless APIs, MCP tools, and a standalone offline build.

It is useful anywhere Markdown needs to remain the source of truth while users edit either the source or rendered view: docs, dashboards, CMS fields, internal tools, local/offline apps, chat UIs, and human/LLM co-editing workflows.

Try the Editor | Live Site | Examples | Downloads | Docs

Split-mode view: Markdown source on the left, rendered preview on the right — with rendered Mermaid diagrams, MathJax equations, syntax-highlighted code, and other rich fences.

Why Quikdown?

Most Markdown libraries are either parsers, previewers, textarea editors, or large editor frameworks. Quikdown is meant to be a compact Markdown document surface: parse Markdown, render rich fences, edit source or rendered output, round-trip back to Markdown, and embed the whole thing with one import.

The original use case was LLM-assisted editing, where a model and a human both work on the same Markdown document. But the same requirements show up in many ordinary applications: CMS fields, documentation tools, internal dashboards, report builders, offline field tools, chat interfaces, and apps that need diagrams, math, tables, charts, maps, or other rich content inside Markdown without adopting a heavyweight editor stack.

Quikdown intentionally does not try to be a full CommonMark implementation or a ProseMirror replacement. It covers a practical Markdown subset and focuses on small size, safe defaults, bidirectional editing, rich fenced content, offline deployment, and simple application integration.

Highlights

Drop-in editor — one

, one import. Source, split, and preview modes with toolbar, themes, undo/redo, copy-as-rich-text, and rich fence rendering.

Bidirectional Markdown Parser Lib — convert Markdown → HTML and supported Quikdown HTML → Markdown. Edit the rendered side and get Markdown back.

Rich fences — built-in editor renderers for syntax-highlighted code, Mermaid, MathJax, SVG, CSV/TSV/PSV tables, GeoJSON maps, STL models, ABC music notation, Vega/Vega-Lite charts, and sanitized raw HTML.

Small core — approximately 15–17 KB minified for the parser, with zero runtime dependencies.

Safe by default — HTML is escaped, unsafe URL schemes are blocked, and the core parser uses no eval or dynamic regular expressions.

Offline standalone build — a self-contained editor bundle for air-gapped, regulated, local, field, or desktop-app use with rich fence support.

LLM/agent friendly — stream Markdown into the editor, let an agent modify the document, and roll back mistakes with programmatic undo/redo.

Headless API — run the editor without a toolbar and wire it into your own UI or automation layer.

MCP server — 24 tools for parsing, file operations, and editor control over JSON-RPC 2.0.

Structured output — companion AST, JSON, YAML, and AST-to-HTML modules.

Modules

Use only the pieces you need.

Module Size Purpose

quikdown.js ~15–17 KB Markdown → HTML parser. Safe defaults, fence plugin callbacks, inline styles or CSS classes.

quikdown_bd.js ~22.7 KB Bidirectional Markdown ↔ HTML conversion.

quikdown_edit.js ~102.9 KB Drop-in split-view headless editor control with undo/redo, toolbar, themes, copy-as-rich-text, and lazy-loaded fence plugins.

quikdown_edit_standalone.js ~7.7 MB / ~1 MB gzipped Offline editor with all fence libraries bundled. No CDN required.

quikdown_mcp.js ~26 KB MCP server with 24 tools for AI agents.

quikdown_ast / json / yaml / ast_html ~5–8 KB each Companion modules for structured output and AST-based rendering.

Install

Quikdown is available on npm and can also be loaded directly from UNPKG or jsDelivr.

npm install quikdown

Browser via ES module

Browser via UMD

Quick start

Quikdown has three common entry points: the core parser, the bidirectional parser, and the editor.

Markdown → HTML

Use quikdown when you only need Markdown rendering.

import quikdown from 'quikdown';

const markdown = '# Hello World\n\nThis is Markdown.'; const html = quikdown(markdown);

document.body.innerHTML = html;

You can choose inline styles or CSS classes.

const html = quikdown(markdown, { inline_styles: true });

Markdown ↔ HTML

Use quikdown_bd when you need rendered HTML that can be converted back to Markdown.

import quikdown_bd from 'quikdown/bd';

const html = quikdown_bd(markdown); const markdownAgain = quikdown_bd.toMarkdown(html);

Quikdown’s HTML → Markdown conversion is designed for Quikdown-generated HTML and supported Markdown structures. It is not intended to be a generic arbitrary-HTML-to-Markdown converter.

Standard Markdown structures such as headings, text styles, links, lists, blockquotes, tables, and code fences are supported. For custom fences, Quikdown relies on its tag system or third-party handlers to provide reverse conversion.

Drop-in editor

Use QuikdownEditor when you want source, split, or preview editing in the browser.

const editor = new QuikdownEditor('#container', { mode: 'split', // 'source', 'split', or 'preview' theme: 'auto', // 'light', 'dark', or 'auto' plugins: { highlightjs: true, mermaid: true, mathjax: true } });

editor.setMarkdown('# Content\n\nTo be quik or not to be.'); const markdown = editor.getMarkdown();

The editor can also run headless, without the built-in toolbar.

const editor = new QuikdownEditor('#container', { mode: 'split', showToolbar: false });

editor.setMarkdown(markdown); editor.undo(); editor.redo(); editor.setTheme('dark'); editor.setMode('preview');

Rendering support (fences)

Quikdown’s editor can render common fenced block formats while preserving the original fence source for round-trip editing. Note that quikdown itself can't support reverse editing for specialty fences such as mermaid or MathJax but callbacks are provided so those can be handled on a case-by-case basis.

Built-in editor fence handlers include:

js, javascript, python, c, cpp, and other code fences via highlight.js

mermaid diagrams

math, tex, latex, and katex equations via MathJax

svg inline graphics

csv, tsv, and psv tables

geojson maps via Leaflet

stl 3D models via Three.js

abc and music sheet music via ABCJS

vega, vega-lite, and vegalite charts

html fences sanitized with DOMPurify

Fence libraries are lazy-loaded by the editor when needed. Use the standalone build when you need everything bundled with no network access.

Custom fence handlers use a small callback API.

const fencePlugin = { render: (content, language) => { if (language === 'mermaid') { return renderMermaid(content); }

return undefined; // fall back to default handling } };

const html = quikdown(markdown, { fence_plugin: fencePlugin });

Security model

Quikdown’s core parser escapes HTML by default. Only safe Markdown constructs become HTML unless a fence plugin explicitly renders additional content.

const unsafe = ' bold'; const safe = quikdown(unsafe);

// bold

Security-related defaults and checks include:

HTML escaped by default

URL sanitization for links and images

Blocking of javascript:, vbscript:, and non-image data: URIs

No eval

No dynamic RegExp

Static regex patterns checked for ReDoS risk

DOMPurify used by the built-in editor for raw HTML fences

ESLint security checks enforced in CI

Fence plugins are trusted extension points. If a custom plugin returns HTML, that plugin is responsible for sanitizing what it renders.

For the full model, see docs/security.md.

AST, JSON, and YAML output

Quikdown includes companion libraries for converting Markdown into structured data formats.

import quikdown_ast from 'quikdown/ast'; import quikdown_json from 'quikdown/json'; import quikdown_yaml from 'quikdown/yaml'; import quikdown_ast_html from 'quikdown/ast-html';

const markdown = '# Hello\n\nWorld bold';

const ast = quikdown_ast(markdown); const json = quikdown_json(markdown); const yaml = quikdown_yaml(markdown);

const html = quikdown_ast_html(ast);

The AST parsers are forgiving and handle malformed Markdown gracefully without throwing errors. See AST Documentation for the complete node type reference.

Common integration patterns

Quikdown supports three common integration styles.

Pattern Use when Entry point

Parse-only You need safe Markdown rendering or structured output in an app import quikdown from 'quikdown'

File agent An AI agent reads and writes Markdown/HTML files in a repo sandbox npx quikdown-mcp --root=.

Doc copilot A human edits in the browser while an agent controls the same document node examples/mcp-doc-host/start-mcp.js

The parse-only path is the default: zero config, browser or Node.js, and no runtime dependencies in the core parser.

The file-agent path adds MCP filesystem tools under a sandbox root. This is useful when the human stays in Cursor, VS Code, or another file editor.

The doc-copilot path opens a browser editor and lets an MCP client control the same live document through a Node bridge.

For details, see docs/llm-integration.md, docs/quikdown-mcp.md, and examples/mcp-doc-host.

LLM and agent workflows

Quikdown fits the loop where a model writes Markdown, a human sees rendered output, and both continue editing the same document.

Pattern Demo / docs

AI canvas: chat + document editor examples/ai-canvas

Agent tool-calling on editor content examples/llm-tool-editor

MCP doc copilot examples/mcp-doc-host

Stream into QuikdownEditor examples/llm-stream-editor

Stream tokens into rendered HTML integration-llm-stream

Chat bubbles with Markdown quikchat and integration example

Overview: docs/llm-integration.md

MCP server

Quikdown includes an MCP server that lets AI agents parse Markdown, convert between formats, read/write files, and, with a doc host, control the editor — all over JSON-RPC 2.0.

Two paths

Path Human UI Command

A — IDE Cursor / VS Code file editor; no browser npx quikdown-mcp --root=.

B — Doc copilot Browser tab with QuikdownEditor; Node host bridges MCP node examples/mcp-doc-host/start-mcp.js

Path A is for repo/file workflows. Path B is for live document workflows where the human edits in the browser while the agent uses MCP against the same editor state.

npm install quikdown n

[truncated for AI cost control]