Velotype: a Rust and GPUI Markdown editor with block-based WYSIWYG editing

The problem Velotype solves: editing Markdown without a preview pane

Most Markdown editors split the window in two. You type on the left, a rendered copy appears on the right, and you spend part of every editing session checking that the two halves agree. Velotype removes that loop. The README describes a block-based model where "Markdown structure is represented as editable blocks," so the rendered text is the thing you type into, and there is no separate preview surface to keep in sync.

The project also keeps a raw source mode, which matters more than it sounds. WYSIWYG editors tend to hide the syntax that a writer occasionally needs to see or hand-edit: reference-style link definitions, footnote markers, comment blocks. Velotype lets you switch between rendered editing and Markdown source text for "common authoring workflows," so the escape hatch is part of the design rather than an afterthought.

The intended user is a desktop writer who wants a native application rather than an editor wrapped in a web runtime. The README states plainly that Velotype renders through GPUI "without depending on Electron, Tauri, or any WebView shell." That is a positioning choice, not a feature list, and it tells you who the project is arguing with.

How the block model and GPUI rendering fit together

The architecture table in the README splits the code into layers. The `editor` layer holds window-level state: view mode, save and close flow, undo, selection, source mapping, tree mutation, export, and file drop. Below it, `components::block` owns the editable block runtime, GPUI input handling, block rendering, block events, and the runtime state for images, tables, and code. A third layer, `components::markdown`, holds the data models and the parse and serialize helpers for inline text, links, images, footnotes, tables, HTML, and code highlighting.

The interesting part is the split between `components::block` and `components::markdown`. Blocks are the editing surface; the markdown layer is the canonical representation. That is why the README can promise "canonical Markdown serialization" while also offering a rendered editing mode: the document you see is a tree of blocks, and serialization walks that tree back out to Markdown text. Source mapping in the `editor` layer is what makes the switch between modes possible without losing your place.

Parsing is handled with a stated preference for stability over completeness. The README says the parser "follows a standard-oriented strategy and falls back to raw Markdown in unstable cases." In practice that means a construct the parser cannot handle confidently is shown as literal Markdown rather than guessed at. That is the right default for an editor, but it also means the rendered view is not a guarantee that every extended syntax construct round-trips cleanly.

Code highlighting is compiled in through Cargo features rather than added at runtime. The default feature set includes `code-highlight-core`, `code-highlight-official`, `code-highlight-config`, and `html-native`, and `code-highlight-official` pulls in tree-sitter grammars for Rust, JavaScript, TypeScript, JSON, Markdown, Bash, C, C++, C#, CSS, Go, HTML, Java, PHP, Python, and Ruby. If you build with `--no-default-features`, you are choosing a smaller binary and losing those grammars.

Installing Velotype from a release or building it with Cargo

The README points first at the Releases page, where builds are published per platform. On Windows and Linux you download a `.zip` or `.tar.gz`, unzip it, and run the executable. There is no installer step and no dependency to resolve, because the README describes the app as a "portable single file" after compilation.

macOS gets two paths. The `.app` package is unzipped and dragged wherever you want it. The `.pkg` installer is marked as recommended in the README and installs to `/Applications` while configuring the `velotype` command-line tool through `postinstall` and `preuninstall` scripts. If you use the `.app` instead, the CLI is installed from the menu with Help, then Install CLI Command, and you will be asked for an administrator password.

The README is explicit about what happens if you move the app afterward: the symlink becomes invalid and running `velotype` reports "command not found." That is a real papercut for anyone who reorganizes their Applications folder.

Building from source needs Git, Cargo, a Rust toolchain with Rust 2024 edition support, and whatever native build dependencies GPUI and your platform toolchain require. The README does not enumerate those platform packages.

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

cargo build --release

The README states the artifact lands under `target/release` and can be used directly. The package version in `Cargo.toml` is `0.7.2`, matching the most recent release listed. The crate declares `edition = "2024"`, so an older toolchain will fail at the manifest rather than at a confusing compile error later.

Custom themes and language packs: partial config with inherited defaults

Velotype treats visual themes and UI language packs as separate files. A theme can override global colors, fonts, sizes, menus, dialogs, table controls, image placeholders, code highlighting colors, and layout tokens. The inheritance rule is the useful part: missing fields or empty values fall back to a built-in base theme, either `velotype` or `velotype-light`, chosen by the `base_theme_id` field. If that field is empty or invalid, the fallback is the `velotype` theme values. A custom theme file can therefore be a handful of lines.

Language packs follow the same partial-configuration strategy. Missing strings fall back to English, and an imported pack is normalized before it is written into the app configuration directory.

The README provides two starting points, `assets/custom-theme.example.jsonc` and `assets/custom-language.example.jsonc`, and describes importing them from the app through Theme, then Add Theme Config, or Language, then Add Language Config. JSONC comments are accepted on import; files the app saves back are strict JSON. That asymmetry is worth knowing before you hand-edit a saved config and expect comments to survive.

The README closes this section with a warning that the project "is evolving rapidly, so theme field changes may occur frequently." Treat a theme file as something you will need to revisit after upgrades, not a one-time investment.

HTML and PDF export, and where the pipeline stops

Export covers HTML and PDF. The README says HTML export maps the active theme into CSS, and PDF export reuses the same themed HTML pipeline so the visual output stays consistent between the two. Reusing one pipeline is a sensible decision: it means a single theming path to maintain, and it means PDF output cannot drift from HTML output in ways a separate renderer would allow.

The README does not describe pagination controls, page size configuration, or how PDF rendering is performed. If your workflow depends on specific page geometry, that is something to check on your own documents rather than assume.

The roadmap marks two items as done: optimizing parsing and rendering for very large Markdown documents, and workspace mode with outline parsing. Three items remain unchecked: built-in image hosting, more complete IME behavior, and, by implication, continued syntax coverage. The unchecked IME item is the one to weigh if you write in a language that composes characters during input, because the README lists it as unfinished work rather than a solved problem.

Limitations, and the cases where Velotype is the wrong pick

The README calls the project early, and the roadmap agrees. There is no plugin or extension system described anywhere in the README, so if you need to extend the editor with custom behavior beyond themes and language packs, the extension point does not exist yet. Theme and language files are the only documented customization surface.

There is no mention of collaborative editing, sync, or a server component. This is a local desktop application that opens files.

The macOS CLI symlink is fragile by design: moving or deleting `Velotype.app` breaks it, and the README documents the resulting "command not found" rather than offering a repair command. The `.pkg` path avoids this because the installer manages the symlink, which is presumably why the README recommends it.

The theme format is explicitly unstable. The README warns that theme field changes may occur frequently, which means a custom theme is maintenance you have signed up for. Combined with the unchecked IME work, the honest summary is that Velotype is a project to evaluate on a real document, not one to standardize a team on today.

One more boundary: the repository's `Cargo.toml` declares `license = "Apache-2.0"` and the repository contains a `LICENSE-APACHE` file, but the repository metadata reports the license as NOASSERTION, meaning the platform has not classified it. If license terms matter to your organization, read the LICENSE-APACHE file directly rather than trusting the badge in the README.

How Velotype differs from Typora and other Markdown editors

The closest comparison is Typora, which also presents a single rendered editing surface rather than a split preview. The difference in approach is the implementation stack and the resulting distribution. Typora ships as a packaged desktop application; Velotype is a Rust binary built on GPUI that the README describes as a single executable with no installer requirement on Windows and Linux. If you care about the size of the runtime you are shipping or about avoiding a bundled web engine, that is the axis where Velotype makes its argument.

Against a plain text editor with a Markdown preview, the difference is the block model. In a text editor with preview, the file on disk is the source of truth and the preview is derived. In Velotype, the block tree is what you edit and Markdown serialization is the output. That inverts which representation the application treats as primary, and it is the reason the project can offer rendered editing without a synchronization loop.

Against editors built on web technologies, the comparison is GPUI itself. GPUI is a Rust GUI framework, and the `Cargo.toml` pins it at version `0.2` with the `runtime_shaders` feature enabled. That is a young dependency, and building Velotype from source means building against whatever that version requires on your platform. The README does not list those platform build dependencies, which is the practical cost of the native approach.

Release cadence and what an upgrade costs you

The listed releases run from v0.6.7 on 2026-07-01, to v0.7.0 on 2026-07-14, to v0.7.2 on 2026-08-14. The last push to the repository was on 2026-09-15, and the repository is not archived. That is a steady pace of small version bumps rather than long-lived major releases, which fits the README's own description of a project that is still early.

The upgrade cost is concentrated in two places. Theme files are the first: the README states that theme field changes may occur frequently, so a custom theme should be treated as something to re-check after each version bump rather than a set-and-forget asset. Language packs are the second, though the fallback to English for missing strings softens the impact of a pack that has not kept up.

Because releases are distributed as standalone binaries, upgrading means replacing the executable rather than running a package manager. On macOS with the `.pkg` installer, the installer scripts handle the CLI symlink; with the `.app` package, you reinstall the CLI from the menu after replacing the bundle. The README does not document a rollback procedure, so if you need to pin a working version, keep the previous archive.

On licensing: `Cargo.toml` declares Apache-2.0 and a `LICENSE-APACHE` file is present at the repository root. Apache-2.0 is a permissive license with an explicit patent grant. That is a general description of the license, not advice about your situation; read the file if the terms affect what you plan to do.

Editorial conclusion

Adopt Velotype if you want a native, no-WebView Markdown editor and you are comfortable with pre-1.0 software whose theme fields the README says may change frequently; the block model and source-mode fallback are the parts worth evaluating first. Skip it if you need a stable plugin API, collaborative editing, or a documented rollback path, none of which appear in the README. Before relying on it, build from source with cargo build --release, open a document with tables, footnotes, and HTML blocks, and check that the export pipeline produces the HTML and PDF you expect.

Frequently asked questions

Official sources

1. Issues
2. manyougz/velotype on GitHub
3. README
4. Releases