MarkBun

中文 | English

📝 A fast, beautiful, Typora-like markdown desktop editor

MarkBun is an open-source, cross-platform markdown editor designed for seamless writing. Like Typora, it provides a distraction-free WYSIWYG editing experience where markdown syntax fades away to reveal beautifully formatted content.

Mark (from Markdown) + Bun (from Electrobun) = MarkBun

🍞 Why "MarkBun"?

In the Age of AI, Markdown is the lingua franca — the universal currency of digital communication. Learn Markdown, earn your bread. It's that simple. (Plus, "Markbun" sounds way tastier than "Plaintextbun")

🚧 Development Status

⚠️ Early Development Stage

MarkBun is currently in active development.

Current Status:

✅ Electrobun desktop framework configured

✅ React + Vite + Tailwind CSS setup

✅ Development environment with HMR

✅ Milkdown WYSIWYG editor integration

✅ File operations (New, Open, Save, Save As)

✅ Dark mode support

✅ Toolbar and status bar (hidden by default)

✅ File explorer sidebar (v0.2.0)

✅ Outline navigation (v0.2.0)

✅ Quick Open (Ctrl/Cmd+P)

✅ Auto-save (v0.3.0)

✅ Settings UI (v0.3.0)

✅ Multi-monitor support (v0.3.0)

✅ Three-layer file protection (v0.4.0)

✅ Export to PNG/HTML (v0.4.0)

✅ Math equations (v0.4.0)

✅ Find & Replace (v0.5.0)

✅ Command Palette (v0.5.0)

✅ Session Persistence (v0.5.0)

✅ Windows Support (v0.5.0)

✅ AI Chat Assistant (v0.6.0)

✅ Mermaid Diagrams & HTML Blocks (v0.7.0)

✅ Frontmatter Support (v0.7.0)

✅ Editor Polish & Bug Fixes (v0.8.0)

See ROADMAP.md for detailed development phases.

✨ Features

Design Philosophy

MarkBun follows a chromeless editing philosophy inspired by the pioneering work of iA Writer and Typora. The interface is intentionally minimal — all toolbars, title bars, and status bars are hidden by default to eliminate visual distractions and keep you focused on your content.

When you need them, every UI element can be instantly toggled via the View menu or keyboard shortcuts. This approach puts the written word at the center of the experience, not the application chrome.

Core Features

🎯 Seamless WYSIWYG Editing - Write markdown naturally without distraction
⚡ Lightning Fast - Built with Bun and native webviews for <50ms startup
🎨 Beautiful Typography - Carefully crafted themes and styles
🖼️ Chromeless Interface - Distraction-free writing with all UI elements hidden by default
🌙 Dark Mode - Easy on the eyes for night writing
📁 File Management - Built-in file browser with folder support
🔍 Outline Navigation - Jump to any heading instantly
⚡ Quick Open - Fuzzy file finder with Ctrl/Cmd+P
🧮 Math Support - LaTeX equations with live preview
📊 Tables - Intuitive table editing with header styling
💾 Auto Save - Hybrid throttle/debounce strategy
⚙️ Settings - Persistent settings with UI
🖥️ Multi-Monitor - Window position saved per display with smart fallback
🛡️ File Protection - Atomic write, crash recovery, and version history
📤 Export - Export to PNG and HTML
🔍 Find & Replace - Search with highlighting across WYSIWYG and code blocks (Cmd/Ctrl + F)
🎛️ Command Palette - Unified command palette with fuzzy search and history (Cmd/Ctrl + P)
💾 Session Restore - Cursor position and scroll state saved between sessions
🪟 Windows Support - Native menu bar, icons, and CI for Windows
⌨️ Keyboard Shortcuts - Comprehensive shortcuts for formatting and navigation
🔤 Source Mode - Toggle between WYSIWYG and source code editing (Cmd/Ctrl + /)
🤖 AI Assistant - Multi-provider AI chat with document editing tools (OpenAI, Anthropic, Ollama, etc.)
📊 Mermaid Diagrams - View Mermaid diagrams with zoom and pan support
🌐 HTML Blocks - Render HTML blocks with DOMPurify preview support
📝 Frontmatter - Display YAML frontmatter in the editor
🌐 i18n - Multi-language support (English, Chinese, Japanese, Korean, etc.)
🗂️ Workspace Persistence - File explorer root path restored between sessions
🪟 Smart Window Behavior - Open files and folders in new windows when needed

🚀 Quick Start

Prerequisites

Bun 1.0+
macOS 11+, Windows 10+, or Linux

Installation

# Install dependencies
bun install

# Development without HMR (uses bundled assets)
bun run dev

# Development with HMR (recommended)
bun run dev:hmr

macOS Note

Since MarkBun is not yet code-signed, macOS Gatekeeper may show a "damaged" warning. Run this command after installing:

xattr -cr /Applications/MarkBun.app

Build

# Build for canary release
bun run build:canary

# Build for stable release
bun run build:stable

How HMR Works

When you run bun run dev:hmr:

Vite dev server starts on http://localhost:5173 with HMR enabled
Electrobun starts and detects the running Vite server
The app loads from the Vite dev server instead of bundled assets
Changes to React components update instantly without full page reload

When you run bun run dev (without HMR):

Electrobun starts with file watch and loads from views://mainview/index.html
You need to rebuild (bun run build:canary) to see changes

🏗️ Tech Stack

Technology	Purpose
Milkdown	WYSIWYG Markdown editor core
Electrobun	Cross-platform desktop framework
CodeMirror	Source mode editor
Bun	JavaScript runtime and bundler
TypeScript	Type-safe development
Tailwind CSS	Utility-first styling
Zod	Settings schema validation
i18next	Internationalization

📁 Project Structure

markbun/
├── src/
│   ├── bun/                  # Main process (Electrobun/Bun)
│   │   ├── index.ts          # Main entry point and RPC handlers
│   │   ├── menu.ts           # Application menus
│   │   ├── services/         # Backend services (settings, backup, uiState)
│   │   └── ipc/              # IPC handlers
│   │
│   ├── mainview/             # Renderer process (WebView)
│   │   ├── components/       # React components
│   │   │   ├── editor/       # Milkdown/Crepe editor wrapper
│   │   │   ├── file-explorer/# File explorer sidebar
│   │   │   ├── layout/       # Toolbar, StatusBar, TitleBar, Sidebar
│   │   │   ├── outline/      # Outline navigation
│   │   │   ├── quick-open/   # Quick Open dialog
│   │   │   ├── settings/     # Settings dialog
│   │   │   └── recovery-dialog/ # Crash recovery dialog
│   │   │
│   │   ├── hooks/            # Custom React hooks
│   │   ├── lib/              # Utilities and helpers
│   │   ├── i18n/             # Internationalization (8 locales)
│   │   ├── styles/           # Global styles
│   │   ├── main.tsx          # React entry point
│   │   ├── App.tsx           # Main App component
│   │   └── index.html        # HTML entry
│   │
│   └── shared/               # Shared types, settings schema, command registry, and utilities
│
├── docs/                     # Documentation
│   └── architecture.md       # Architecture overview
│
├── electrobun.config.ts      # Electrobun configuration
├── vite.config.ts            # Vite configuration
├── tailwind.config.js        # Tailwind configuration
├── package.json
└── README.md

🎮 Usage

Basic Editing

New File: Cmd/Ctrl + N
Open File: Cmd/Ctrl + O
Save: Cmd/Ctrl + S
Save As: Cmd/Ctrl + Shift + S

Interface Controls

MarkBun uses a chromeless interface — all toolbars and UI elements are hidden by default for distraction-free writing. Toggle UI elements via the View menu or shortcuts:

UI Element	Menu Command	Default State
Title Bar	`View → Show Title Bar`	Hidden
Toolbar	`View → Show Tool Bar`	Hidden
Status Bar	`View → Show Status Bar`	Hidden
Sidebar	`View → Show Sidebar`	Hidden (`Cmd/Ctrl + Shift + B`)
Dark Mode	`View → Toggle Dark Mode`	`Cmd/Ctrl + Shift + D`
Source Mode	`View → Toggle Source Mode`	`Cmd/Ctrl + /`
Settings	`MarkBun → Preferences`	`Cmd/Ctrl + ,`

Formatting Shortcuts

Action	Shortcut
Bold	`Cmd/Ctrl + B`
Italic	`Cmd/Ctrl + I`
Inline Code	`Cmd/Ctrl + Shift + C`
Strikethrough	`Cmd/Ctrl + Shift + ~`
Highlight	`Cmd/Ctrl + Shift + H`
Inline Math	`Ctrl + M`
Link	`Cmd/Ctrl + K`
Image	`Cmd/Ctrl + Shift + I`

Paragraph Shortcuts

Action	Shortcut
Heading 1-6	`Cmd/Ctrl + 1/2/3/4/5/6`
Paragraph	`Cmd/Ctrl + 0`
Increase Heading Level	`Cmd/Ctrl + =`
Decrease Heading Level	`Cmd/Ctrl + -`
Bullet List	`Alt + Cmd/Ctrl + U`
Ordered List	`Alt + Cmd/Ctrl + O`
Task List	`Alt + Cmd/Ctrl + X`
Quote	`Alt + Cmd/Ctrl + Q`
Code Block	`Alt + Cmd/Ctrl + C`
Math Block	`Alt + Cmd/Ctrl + B`
Horizontal Rule	`Alt + Cmd/Ctrl + -`
Table	`Alt + Cmd/Ctrl + T`

🎨 Customization

Settings

Settings are stored in ~/.config/markbun/settings.json:

{
  "__version": 1,
  "general": {
    "autoSave": true,
    "autoSaveInterval": 2000,
    "language": "en"
  },
  "editor": {
    "fontSize": 15,
    "lineHeight": 1.65
  },
  "appearance": {
    "theme": "system",
    "sidebarWidth": 280
  },
  "backup": {
    "enabled": true,
    "maxVersions": 20,
    "retentionDays": 30,
    "recoveryInterval": 30000
  }
}

UI state is stored separately in ~/.config/markbun/ui-state.json:

{
  "showTitleBar": false,
  "showToolBar": false,
  "showStatusBar": false,
  "showSidebar": false,
  "sidebarWidth": 280,
  "sidebarActiveTab": "files",
  "windowX": 200,
  "windowY": 200,
  "windowWidth": 1200,
  "windowHeight": 800
}

The window position and size are automatically saved and restored on restart. If the saved position is outside the visible screen area (e.g., when a monitor is disconnected), the window will be reset to a safe default position on the primary display.

Multi-Monitor Support

MarkBun fully supports multi-monitor setups:

Window position is saved per display
Automatically detects when a display is disconnected
Falls back to primary display when the original display is unavailable
Validates window visibility before restoring to ensure the window is always accessible

🛠️ Development

Scripts

bun run dev            # Start development with file watch
bun run dev:hmr        # Start development with HMR (recommended)
bun run build:canary   # Build canary release
bun run build:stable   # Build stable release
bun run test           # Run tests once
bun run test:watch     # Run tests in watch mode
bun run test:coverage  # Run tests with coverage
bun run lint           # Run typecheck and tests

Adding Milkdown Plugins

bun add @milkdown/plugin-math

🧪 Testing

Running Tests

MarkBun uses Bun's built-in test runner:

# Run all tests
bun test

# Run tests in watch mode (during development)
bun run test:watch

# Run tests with coverage report
bun run test:coverage

Editor Module Tests

After refactoring, the editor module has comprehensive unit tests:

tests/unit/components/editor/
├── types.test.ts              # Type definition tests
├── utils/
│   ├── tableHelpers.test.ts   # Table utility tests
│   └── editorActions.test.ts  # Editor action tests
├── hooks/
│   └── index.test.ts          # React hooks tests
└── commands/
    ├── formatting.test.ts     # Formatting command tests
    ├── paragraph.test.ts      # Paragraph command tests
    └── table.test.ts          # Table command tests

Test Directory Structure:

Tests are in tests/unit/ mirroring the src/ structure
tests/unit/setup.ts - Test helper for simplified imports
Future: tests/integration/ and tests/e2e/ for other test types

Simplified Imports:

// Import from setup.ts instead of long relative paths
import { isTableCell, toggleBold } from '../setup';

Writing Tests

When modifying the editor, you must run tests:

# Before committing
bunx tsc --noEmit  # Type check
bun test           # Run all tests

Test naming convention:

should [expected behavior] when [condition]
Example: should return false when editor is not initialized

Test Coverage

Minimum coverage requirements:

Utils: 90%+
Commands: 80%+
Hooks: 70%+

Generate coverage report:

bun test --coverage

⚠️ Known Issues

Windows double cursor on high-DPI displays: On Windows 11 with display scaling above 100% (e.g., 150%), the app may show two mouse cursors — one normal and one enlarged. This is caused by a missing DPI awareness declaration in the Electrobun framework (electrobun#324). Awaiting an upstream fix.
No native file association support: Double-clicking a .md file or dragging files onto the app icon does not open them (electrobun#304). On macOS, this is partially worked around with an AppleScript droplet wrapper. Windows remains unresolved.
Windows garbled text for non-ASCII languages: Menu labels and file dialogs show garbled text for Chinese, Japanese, and other non-ASCII characters on Windows. This is caused by Electrobun using ANSI Win32 APIs instead of Unicode (Wide) APIs (electrobun#335). Awaiting an upstream fix.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 Roadmap

v0.1.0 (MVP) ✅ Completed

Basic WYSIWYG editing
File open/save
Markdown syntax support
Dark mode

v0.2.0 ✅ Completed

v0.3.0 ✅ Completed

Table header styling
Auto-save (with hybrid throttle/debounce strategy)
Settings UI (General, Editor, Appearance tabs)
UI state persistence (sidebar width, visibility)
Theme management (light/dark/system)
Multi-monitor support with display detection

v0.4.0 ✅ Completed

Three-layer file protection (atomic write, crash recovery, version history)
Export to PNG image
Export to HTML
Math equations (LaTeX inline and block support)

v0.5.0 ✅ Completed

Find & Replace with search highlighting (WYSIWYG and code blocks)
Unified Command Palette (Ctrl/Cmd+P)
Session persistence (cursor/scroll position restore)
Windows platform support (menu bar, icons, CI)

v0.6.0 ✅ Completed

AI Chat Assistant with streaming responses
Multi-provider support (OpenAI, Anthropic, Google, Ollama, DeepSeek, etc.)
Document editing tools (read, edit, write)
Session history persistence and management

v0.7.0 ✅ Completed

Mermaid diagram viewer with zoom and pan
HTML block rendering with DOMPurify preview support
Frontmatter display support
Source mode support for undo/redo/copy/cut/select-all
AI tools image path conversion
Command manifest unification and i18n consolidation

v0.8.0 ✅ Completed

Mermaid hover-to-viewer and fit-to-window
Editor code block copy/paste fixes
HTML block fenced code misidentification fix
Chunked loading boundary fix for fenced code blocks
File explorer root path persistence
New-window file/folder open behavior
AI edit/write auto-save sync
Windows NSIS installer

v1.0.0

Stable release

📋 TODO

Features under consideration for future releases:

📄 License

MarkBun is licensed under the MIT License.

🙏 Acknowledgements

Milkdown - The amazing WYSIWYG markdown framework
Electrobun - Ultra-fast desktop framework
CodeMirror - Source mode editor
ProseMirror - The foundation of Milkdown
Typora - Inspiration for the editing experience

Made with ❤️ by @xiaochong

Name		Name	Last commit message	Last commit date
Latest commit History 274 Commits
.github/workflows		.github/workflows
docs		docs
icon.iconset		icon.iconset
scripts		scripts
src		src
tests/unit		tests/unit
website		website
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README-cn.md		README-cn.md
README.md		README.md
ROADMAP.md		ROADMAP.md
bun.lock		bun.lock
electrobun.config.ts		electrobun.config.ts
llms.txt		llms.txt
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

MarkBun

🚧 Development Status

✨ Features

Design Philosophy

Core Features

🚀 Quick Start

Prerequisites

Installation

macOS Note

Build

How HMR Works

🏗️ Tech Stack

📁 Project Structure

🎮 Usage

Basic Editing

Interface Controls

Formatting Shortcuts

Paragraph Shortcuts

🎨 Customization

Settings

Multi-Monitor Support

🛠️ Development

Scripts

Adding Milkdown Plugins

🧪 Testing

Running Tests

Editor Module Tests

Writing Tests

Test Coverage

⚠️ Known Issues

🤝 Contributing

📝 Roadmap

v0.1.0 (MVP) ✅ Completed

v0.2.0 ✅ Completed

v0.3.0 ✅ Completed

v0.4.0 ✅ Completed

v0.5.0 ✅ Completed

v0.6.0 ✅ Completed

v0.7.0 ✅ Completed

v0.8.0 ✅ Completed

v1.0.0

📋 TODO

📄 License

🙏 Acknowledgements

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages