MDPad

Lightweight Markdown editor for Windows, built with Tauri + React + TipTap.

中文说明 (README_zh.md)

Table of Contents

• Overview

• What's New in v0.2.11

• Highlights

• Supported Markdown and Features

• How to Use

• CLI Export

• Keyboard Shortcuts

• Local Development

• Build and Release

• Project Structure

• Troubleshooting

• References

Overview

MDPad is designed for fast, single-document writing with a desktop-native workflow:

• Open one document per window.

• Keep Markdown as the source of truth.

• Preserve practical note-taking syntax from real-world usage (including some Obsidian-style image embeds).

What's New in v0.2.11

Tiptap 3 official Markdown pipeline

• The rich-text editor has moved from Tiptap 2 plus tiptap-markdown to Tiptap 3 with the official @tiptap/markdown package.

• Markdown documents now enter the editor as Markdown content and save through editor.getMarkdown(), reducing format drift between the visual editor and the source file.

• The table implementation now uses the official Tiptap 3 TableKit, replacing MDPad's older custom table schema and resize path.

Safer rich-text paste behavior

• Clipboard payloads that include text/html are handled by the native ProseMirror/Tiptap paste path instead of being intercepted by MDPad's old sanitizer or Markdown fallback.

• Plain-text Markdown insertion is only used when the clipboard does not contain HTML and the text clearly looks like Markdown.

• Image-file paste remains supported through the attachment-library workflow, but it is isolated from the general rich-text paste path.

Current workspace capabilities

• MDPad continues to open and edit .md, .markdown, .html, .htm, .py, .js, .ts, and .json.

• Markdown keeps the rich-text/source workflow, HTML keeps the preview/source workflow, and code files open directly in the CodeMirror 6 source editor.

• The controlled HTML preview still supports local asset resolution, sandboxed local scripts, and system-browser handling for external links.

Highlights

• Native desktop app for Windows (Tauri v2).

• Tiptap 3 rich-text editing with the official Markdown manager.

• Multi-window workflow (Ctrl+N for a new empty window).

• Open/save/save-as/rename for .md, .markdown, .html, .htm, .py, .js, .ts, and .json.

• Unsaved-change protection on close.

• Slash menu (/ on empty line or Ctrl+/ anywhere).

• Bubble menu for quick inline/block formatting.

• Right-side table of contents rail (H1-H3, collapsed/expanded behavior).

• Dual-view workflow for Markdown and HTML: rich text/source for Markdown, preview/source for HTML.

• CodeMirror 6 source editor for Markdown, HTML, and code files.

• Controlled HTML dynamic preview with local asset resolution and script execution.

• Built-in dark/light mode, UI theme switch (Classic/Modern), and markdown theme switch.

• Built-in locale switch (English/Chinese).

• Attachment library flow for pasted media.

Supported Markdown and Features

Core syntax

Item	Supported	Notes
Headings (# to ######)	Yes	Bubble style picker exposes Paragraph/H1-H4 quickly.
Bold / Italic / Strike	Yes	Markdown roundtrip supported.
Inline code / fenced code	Yes	Code block copy action; Mermaid preview entry from mermaid code blocks.
Blockquote	Yes	Standard markdown blockquote supported.
Lists (bullet/ordered)	Yes	Slash and bubble actions supported.
Task list (- [ ], - [x])	Yes	Rendered as task items; markdown export preserved.
Horizontal rule (---)	Yes	Slash menu includes divider command.
Links	Yes	Bubble action and prompt supported.
Tables (GFM)	Yes	Markdown table import/export plus visual table controls.
Inline math (...)	Yes	Parsed/rendered as inline math nodes.
Block math ($$...$$)	Yes	Parsed/rendered as block math nodes.
Highlight (text)	Yes	Parsed and exported as ....
Mermaid (```mermaid)	Yes	Rendered preview node with switch-back-to-code action.

Media and extended syntax

Item	Supported	Notes
Standard markdown image 	Yes	Width-aware rendering in editor.
Markdown image title	Yes	Preserved in roundtrip.
Image size hints <img src="src" alt="alt" data-width="38.46" />	Yes	Parsed and mapped to editor width/height hints.
Obsidian embed image <img src="img.png" data-width="38.46" data-height-px="200" />	Partial	Parsed for image + optional size option.
Linked image [](link)	Yes	Parsed to image node with link attrs.
Video/audio HTML tags	Yes	<video ...> and <audio ...> are preserved through editor nodes.
Binary media paste	Yes	First paste asks for a global attachment folder, then stores media files there.

Editor interaction features

• Slash command groups: Basic, Insert, Media, Math.

• Bubble menu actions: text style, marks, lists, formulas, link.

• Table float menus for table/row/column/cell operations (insert/delete/align/merge/split/header toggles).

• TOC rail:

  • Tracks headings up to H3.

  • Collapsed state shows 5 keys.

  • Hover/focus expands to at most 20 keys with structure-aware selection.

• Markdown sync pipeline:

  • Debounced HTML-to-Markdown sync during typing.

  • Flush before save/rename/close to reduce data-loss risk.

• Document views:

  • Markdown: rich text or source.

  • HTML: preview or source.

  • Code files: source editor.

How to Use

Window and file workflow

• File menu (top bar):

  • New Window

  • Open

  • Save As

• Dedicated save button in top bar for quick save.

• Double-click file title to rename (when current doc has a file path).

• Drag and drop any supported text file into the window to open it in a new window:

  • .md / .markdown

  • .html / .htm

  • .py / .js / .ts / .json

Theme and language

• Top bar button toggles dark/light mode.

• Status bar toggles:

  • App locale (EN / 中文)

  • Markdown theme (Default, Notion, GitHub, Academic)

  • UI theme (Classic Theme / Modern Theme)

Editing workflow

• Markdown opens in rich text by default on every fresh launch.

• HTML opens in preview by default on every fresh launch.

• Use the document-view toggle in the top bar to switch between rich text / source / preview where applicable.

• Type / on an empty line to open slash command menu.

• Press Ctrl+/ anywhere to force open slash command menu.

• Select text to open bubble menu for inline/block style actions.

• For markdown table text, pressing Enter can convert it into a real table node.

CLI Export

The Windows installer also ships with mdpad-cli, and the installer adds it to the current user's PATH.

Supported commands

mdpad-cli export pdf --input <file> --output <file> [--render-width <px>] [--theme <theme>]
mdpad-cli export png --input <file> --output-dir <dir> [--base-name <name>] [--scope <scope>] [--theme <theme>]
mdpad-cli export svg --input <file> --output-dir <dir> [--base-name <name>] [--scope <scope>] [--theme <theme>]

Supported input types

• Markdown: .md, .markdown
• HTML: .html, .htm

Available options

• --input <file>: required for all export commands.
• --output <file>: required for PDF export.
• --output-dir <dir>: required for PNG and SVG export.
• --render-width <px>: used by PDF export and HTML-to-PNG export. Default: 1280. Valid range: 240 to 3840.
• --theme <theme>: Markdown export theme. One of default, github, notionish, academic.
• --scope <scope>: Markdown export scope. One of document, selection. Default: document.
• --base-name <name>: output file base name for PNG/SVG export.

Notes

• HTML currently supports pdf and png, but not svg.
• Relative --input, --output, and --output-dir paths are resolved against the current terminal working directory.
• PNG/SVG export may generate multiple files depending on pagination.

Examples

mdpad-cli export pdf --input report.html --output report960.pdf --render-width 960

mdpad-cli export pdf --input notes.md --output notes.pdf --render-width 1280 --theme github

mdpad-cli export png --input notes.md --output-dir ./out --base-name notes --theme notionish

mdpad-cli export svg --input notes.md --output-dir ./out --base-name notes --scope selection

Help

mdpad-cli --help

Keyboard Shortcuts

Shortcut	Action
Ctrl+N	New window
Ctrl+O	Open markdown file
Ctrl+S	Save
Ctrl+Shift+S	Save As
Ctrl+/	Open slash menu at cursor
Esc	Close menu/modal where applicable
Double-click title bar blank area	Toggle preset window resize
Double-click file name (top bar)	Rename current file

Local Development

Prerequisites

• Windows 10/11

• Node.js 20+ (recommended LTS)

• pnpm

• Rust toolchain (stable)

• Tauri v2 prerequisites for Windows:

  • Microsoft C++ Build Tools

  • WebView2 runtime

Install dependencies

pnpm install

Frontend-only dev

pnpm dev

Full desktop dev (Tauri)

pnpm tauri:dev

Quality checks

pnpm lint
pnpm test
pnpm test:e2e
pnpm build

Optional Rust check:

cd src-tauri
cargo check

Build and Release

Build installer with patch bump

pnpm tauri:build

• pnpm tauri:build bumps patch version automatically (+0.0.1).

• Version source of truth: package.json.

• Version sync targets:

  • src-tauri/tauri.conf.json

  • src-tauri/Cargo.toml

Build installer without bump

pnpm tauri:build:no-bump

Version scripts

pnpm version:sync
pnpm version:bump:patch

Project Structure

src/
  App.tsx
  features/
    editor/          # TipTap editor, markdown codec, slash/bubble/toc, extensions
    file/            # File dialogs, read/write/rename, unsaved modal, attachment setup
    window/          # Top bar and status bar
  shared/            # i18n, preferences, utils, domain types
src-tauri/
  src/lib.rs         # Tauri commands and window/file backend
  tauri.conf.json    # App/bundle config
scripts/
  version-manager.mjs
e2e/
  *.e2e.test.ts
vitest.e2e.config.ts

Troubleshooting

• spawn EPERM during build in restricted terminals:

  • Re-run command with elevated permissions.

  • Ensure antivirus or endpoint security is not blocking esbuild/Rust toolchain processes.

• If app cannot open markdown via association:

  • Confirm the supported file associations in src-tauri/tauri.conf.json bundle config for .md, .markdown, .html, .htm, .py, .js, .ts, and .json.

• If pasted media does not save:

  • Check attachment library folder setup and write permissions.

Reference Matrix and Acknowledgements

Project	Reference Role	Link	Note
tiptap-starter-kit	Baseline reference	https://github.com/syfxlin/tiptap-starter-kit	Used as a capability and structure comparison target.
Novel	Inspiration	https://github.com/steven-tey/novel	Interaction inspiration for editor UX patterns.
Scratch	Inspiration and comparison	https://github.com/erictli/scratch	Lightweight desktop markdown workflow comparison.