Shiba: a Rust markdown previewer that lives beside your editor

A preview window, not an editor

Shiba is described as a simple, performant and keyboard-centric Markdown browser, and the README says the same thing a different way: a simple Markdown browser to preview documents with your favorite text editor.

That framing is the design decision that everything else follows from. Shiba is not an editor and it does not want to be. It opens a document, renders it, and gets out of the way while you type in Vim, Emacs, or whatever you already use. The feature list confirms it: GitHub-flavored Markdown support with emojis, tables, alerts, Math expressions with Mathjax and diagrams with mermaid.js; watching files or directories and automatically updating the preview efficiently using OS-specific filesystem events such as FSEvents and inotify; automatically scrolling to the last modified position; and all features accessible via keyboard shortcuts, with the note to type ? to know all of them.

The keyboard claim is not a footnote. The list of what the shortcuts cover is long: scroll the article, search text, jump to section, go forward and back through history. The idea is that reading a document and navigating it are keyboard operations, so that the window can be a preview that you drive without reaching for the mouse. Sections also appear in a side navigation bar that highlights the current section, which is how you get a structural view without scrolling.

The audience is people who already have an editing workflow and only want the render half of it, done well and quickly. The primary language of the project is Rust, and the crates.io badge points at a package called shiba-preview rather than shiba.

It is also worth saying what it is not. It is not a note taking application, not a wiki, and not a static site generator. It renders one document at a time, and the value is in how fast and how quietly it does that.

Why the split between Rust and the WebView

The architecture is stated in the feature list and it is the most interesting part of the project.

The performance critical parts are written in Rust: parsing Markdown text, searching the Markdown AST, calculating the last modified position. The core application logic is in Rust too. The thin view logic is written in TypeScript and React, and it runs on the platform-specific WebView.

That division is what makes the performance claim credible rather than marketing. The expensive operations in a markdown previewer are not drawing, they are re-parsing and re-searching a document on every change, and doing that in Rust rather than in a script running inside the WebView is the difference between a preview that keeps up with a fast typist and one that lags.

The dependency list in the Cargo.toml confirms the shape of the work. pulldown-cmark is the Markdown parser, aho-corasick is the string search library used for the text search feature, and memchr is the byte search crate it builds on. regex is there for pattern matching, phf provides a perfect hash map, and indexmap preserves insertion order for those maps. The interprocess crate handles inter-process communication and the notify crate at 8.2.0 is what does the filesystem watching, which is the component that actually delivers the live update.

On the side that a reader might worry about, ammonia is an HTML sanitiser, and it is in the dependency list for a reason. Rendering untrusted markdown to HTML in a WebView is exactly the situation where sanitising matters, and having a dedicated crate in the tree rather than an ad hoc regex pass is the right approach.

The windowing side is tao for the window itself, wry for the WebView, muda for menus and rfd for file dialogs, which is the standard set for a native desktop shell on the Rust side.

The Cargo manifest also shows the release profile choices, and they are performance focused: thin LTO, panic set to abort, and codegen-units set to 1 for the release profile, with a separate bench profile also using thin LTO.

The build.rs file, the fuzz directory, the bench directory and the ui directory together suggest a project that treats the Rust side as the tested part and the WebView side as the presentation layer.

Installing: the docs directory, not the README

The README is honest about this. It points to a docs directory and says all documentations are in the docs directory, with an Installation page at docs/installation.md and a note that more docs will be added.

So the install instructions live in the repository rather than in the README, and the README gives you no command to copy. That is unusual for a small project but it keeps the README short, and the installation page is where you should look first.

What the repository layout tells you about the build is more informative than the README. There is a Makefile whose targets map the three supported platforms onto cargo invocations. The debug and release builds for macOS and Windows differ only in a couple of details, with the Windows targets additionally depending on assets/icon.ico, and the release targets depend on the minified bundle rather than the development one:

target/release/shiba: $(RS_SRC) src/assets/bundle.min.js src/assets/index.html $(CSS)
	cargo build --release

And the macOS application bundle and disk image are generated by scripts, gen_macos_app.bash and gen_macos_dmg.bash, with the .dmg target depending on the .app plus the README and LICENSE. The Windows installer is built with the WiX toolset, with the shiba.msi target pulling in a wix file from assets/wix/shiba.wxs and adding two WiX extensions before running wix build.

The Rust side of that build depends on the JavaScript side, because the frontend bundle is compiled and then embedded. The package.json scripts show the development loop: a watch target running the bundle watcher, the TypeScript checker and cargo watch together, a bundle script, a release script that minifies, and a set of fix and lint targets. The lint target is thorough, running clippy with warnings denied, rustfmt in check mode, tsc with no emit, prettier, eslint and stylelint, all concurrently.

There is also a devtools feature that enables the WebView devtools, which is the sort of switch that only exists because the author uses the tool himself.

Configuration, multiple windows and the v2 warning

Customisation is a YAML file. The README says Shiba is customizable with a YAML config file, pointing at src/assets/default_config.yml, and the listed options are a color theme, keyboard shortcuts and custom CSS.

The presence of a shipped default config inside src/assets is worth noting for anyone hacking on the project, because the config is bundled with the binary rather than read from a user directory, and the repository includes a .yamllint.yml at the root, which means the YAML is linted like code. The same is true of the stylesheets, with .stylelintrc.json and a stylelint invocation in the lint script, and of the TypeScript, with eslint.config.mjs, prettier and tsc all configured. This is a project with a strong opinion about formatting, which is helpful if you plan to contribute and a mild obstacle if you only plan to use it.

Multiple windows are supported, so you can open several documents at once.

Then the warning, which is the first thing in the README and should be the first thing you read: Shiba v2 is a work in progress. The About v2 section says v2 is the complete rewrite of v1 using Rust and platform-specific WebView, and that for v1 you should visit the v1 branch.

The release history makes the shape of the rewrite clear. The tags are all 2.0.0-alpha builds: v2.0.0-alpha.4 from 2026-03-28, alpha.3 from 2026-03-11 and alpha.2 from 2026-02-21. The Cargo version reads 2.0.0-alpha.4, while the package.json still says 2.0.0-alpha.0, which tells you the two build systems track versions separately at this stage.

The design intent for v2 is also in the README: simplicity, performance, keyboard-friendly navigation. The crates.io package is named shiba-preview, and the Cargo categories are gui and text-processing, which is a fairly precise description of what the project is for.

Where a markdown browser is the wrong tool

The scope is narrow by design, and that narrows the audience sharply.

If you want to write, organise and publish notes, this is the wrong tool. Shiba previews a document. It has no note repository, no tagging, no backlinks and no search across a collection of files, and it does not write anything back. If your requirement is a personal knowledge base, a documentation site or a wiki, you need something else, and adding those features to Shiba would be a different project from the one the author describes.

The second limit is that it renders one document at a time, and the navigation is a section outline rather than a document index. The side navigation bar highlights the current section, which helps inside a long document and does not help across many.

The third is the v2 status, which is a real constraint rather than a formality. The v1 branch exists and the README sends you there, so if you need something that has been used in production by other people, v1 is the version with a track record, and v2 is the version with the architecture you probably want. The tradeoff is that v2 is Rust plus a WebView and v1 is not, and the whole point of the rewrite is the Rust core and the platform WebView, so v1 also has the older performance characteristics.

The fourth is the platform WebView itself. Rendering in the system WebView means the preview looks like the browser on that machine, which is a benefit for fidelity, and it also means the rendering engine version is whatever the operating system ships. A document that uses a MathJax or mermaid feature that depends on a recent browser engine may render differently across the platforms Shiba supports.

The realistic alternatives split into two groups. On one side, the editor plugins that preview markdown inside the editor itself, which is the opposite design choice: no separate window, but the preview lives in the editor process and shares its performance budget. On the other, the full markdown viewers and note applications, which are more capable as document managers and heavier as previewers. Shiba sits between them, a fast window for one file.

One more practical point. The Rust core does the work, but the tool still spawns a WebView per window, and the README does not describe memory behaviour with many large documents open at once. If your workflow involves a dozen large files side by side, that is worth measuring on your own machine.

Editorial conclusion

Adopt Shiba if you write markdown in an external editor and want a preview pane that updates on save without a plugin, especially if you value a keyboard-driven interface. Do not adopt v2 for production work yet, since the README marks it as a work in progress, and prefer v1 if you need a settled release. Verify first that the version you install matches the documentation you read, that your platform's filesystem event notifications work through the watcher, and that the YAML config options you want, such as custom CSS and keyboard shortcuts, exist in that version.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. rhysd/Shiba on GitHub