Velotype

A Rust + GPUI native Markdown editor with WYSIWYG and source editing modes.

Editor Showcase

English | 中文

Velotype is a block-based Markdown editor built with Rust and GPUI. It supports both WYSIWYG-style rendered editing and Markdown source-text editing.

The project is still early, but the core direction is stable: native UI, instant rendered editing, source-text fallback, canonical Markdown serialization, and customization across color, typography, spacing, and layout tokens.

Features

• 🧱 Block model: Markdown structure is represented as editable blocks, keeping document structure clear, controllable, and extensible without a preview-pane synchronization loop.
• ⚡ Native UI: Desktop-native rendering based on GPUI, without depending on Electron, Tauri, or any WebView shell.
• ✍️ Editing modes: Velotype supports both WYSIWYG-style rendered editing and raw Markdown source editing for common authoring workflows.
• 🚀 Performance and stability: Rust drives parsing, state updates, and rendering; the parser follows a standard-oriented strategy and falls back to raw Markdown in unstable cases.
• 🎨 Theme customization: Themes can customize global colors, typography, spacing, menus, dialogs, editor layout tokens, and language packs.
• 📦 Portable single file: After compilation, Velotype exists as a single executable file. It requires no installation, stays natively portable, and targets Windows, Linux, and macOS.

Velotype already supports exporting the current Markdown document to HTML and PDF. HTML export maps the active theme into CSS, while PDF export reuses the same themed HTML pipeline so visual output stays consistent.

Velotype targets Windows, Linux, and macOS. The app is naturally suitable for distribution as a standalone binary; release builds can run directly without installation.

Quick Start

1. Download a release

Download the build for your platform from the Velotype Releases page.

Windows and Linux Users

• Download the corresponding .zip or .tar.gz file
• Unzip to get the executable
• Run directly

macOS Users

Two installation options are available:

Option 1: Single .app package

• Download velotype-*.zip file
• Unzip to get Velotype.app
• Drag to /Applications or any location
• Double-click to run

Option 2: PKG Installer(Recommended)

• Download velotype-*.pkg file
• Double-click to run the installer
• Automatically installs to /Applications
• Automatically configures command-line tool velotype

If using the PKG installer: The CLI command is configured automatically during installation. The PKG installer manages the symlink automatically via its postinstall / preuninstall scripts. You can still manually trigger installation/uninstallation while in use.

If using the .app package: Install or Uninstall the CLI command directly from the menu:

1. Open Velotype.app
2. Click the menu Help → Install CLI Command
3. Enter administrator password
4. Done!

Be careful, if you move or delete Velotype.app, the symlink will automatically become invalid. Running velotype will report "command not found".

2. Build from source

Prerequisites:

• Git
• A Rust toolchain with Rust 2024 edition support
• Cargo
• Platform-native build dependencies required by GPUI and the system toolchain

Build Velotype locally:

git clone https://github.com/manyougz/velotype.git

cargo build --release

If everything works, the build artifact will be stored under target/release. You can use the executable directly.

Roadmap

Velotype already supports almost all basic Markdown syntax and most commonly used extended Markdown syntax, including headings, paragraphs, lists, task lists, quotes, callouts, tables, code blocks, inline formatting, links, reference-style links and images, footnotes, standalone images, comment blocks, and safe native HTML handling.

Syntax support will continue to improve. Planned work includes:

• Optimize the parsing and rendering capabilities for extremely large Markdown documents
• Workspace Mode and Outline Parsing
• Built-in image hosting
• More complete IME behavior

Theme Customization & Translation

Velotype separates visual themes from UI language packs. Theme files can override global colors, typography, dimensions, menus, dialogs, table controls, image placeholders, code highlighting colors, and layout-related tokens. Missing fields or empty values inherit the built-in Velotype defaults, so a custom theme can be very small or fully override the default look.

Language packs use the same partial-configuration strategy. Missing strings fall back to English, and imported language packs are normalized before being written into the app configuration directory.

Start with the example files:

• Custom theme JSONC
• Custom language JSONC

In the app, use Theme -> Add Theme Config or Language -> Add Language Config to import a .json or .jsonc file. JSONC comments are accepted for writing and sharing examples; normalized configuration files saved by the app are strict JSON.

Thank you for helping translate Velotype or enrich the Velotype theme ecosystem. The project is evolving rapidly, so theme field changes may occur frequently.

Architecture

Layer	Responsibility
editor	Window-level editor state: view mode, save/close flow, undo, selection, source mapping, tree mutation, export, and file drop.
components::block	Editable block runtime, GPUI input handling, block rendering, block events, image/table/code runtime state.
components::markdown	Markdown data models and parse/serialize helpers for inline text, links, images, footnotes, tables, HTML, and code highlighting.
config	Velotype behavior and theme configuration interfaces.
export	HTML and PDF export pipelines.
theme	Visual theme tokens, built-in theme defaults, imported custom themes, and the global theme manager.
i18n	Built-in UI strings, imported language packs, system locale matching, and runtime language selection.
net	HTTP client integration for remote image loading.

The editor uses a native block tree as its runtime model. During import, stable supported Markdown is converted into structured blocks; during save, the block tree is serialized back into canonical Markdown. For syntax that is not stable enough in the current runtime, Velotype preserves the original source and keeps it visible and editable.

Contributing

This repository is still moving fast. When reporting parsing or rendering issues, please fill out the issue template so the problem can be reproduced and handled efficiently.

For code changes, we recommend developing on the dev branch first and keeping patches small. Please extend the existing parser/runtime model instead of replacing the current implementation wholesale.

License

Velotype is licensed under the Apache License 2.0.

Star History