birta 0.7.0

Preview markdown files in the browser with GitHub-style rendering
Documentation

 

Features

  • GitHub-style rendering — full GFM compliance via comrak, including tables, task lists, footnotes, alerts, and math
  • Live reload — file changes push to the browser instantly over WebSocket
  • Raw mode — toggle between rendered preview and syntax-highlighted source with line numbers
  • 11 bundled themes — github, catppuccin, dracula, gruvbox, nord, rose-pine, tokyo-night, and more, with runtime hot-swap
  • Syntax highlighting — server-side via syntect, with per-theme tmTheme support
  • Reading mode — distraction-free viewing with scroll progress indicator
  • Single binary — no runtime dependencies, no Node.js, no Python
  • Directory navigation — relative markdown links are clickable, letting you browse across files in a project
  • Static export — render a self-contained, portable HTML bundle of a file and everything it links to, with assets copied in — no server required
  • Interactive checkboxes — click task list items in the browser to toggle them in the source file
  • Stdin support — pipe markdown from any source: cat notes.md | birta -

 

Quick Start

cargo install birta
birta README.md

Your browser opens with a live preview. Edit the file — the browser updates automatically.

 

Installation

cargo install birta

brew install hugvit/tap/birta

git clone https://github.com/hugvit/birta.git
cd birta
cargo install --path .

 

Usage

Preview a file with the default theme (github):

birta README.md

Use a specific theme in light mode:

birta --theme catppuccin --light README.md

View the raw markdown source with syntax highlighting:

birta --raw README.md

Distraction-free reading:

birta --reading-mode --no-header README.md

Preview from stdin:

cat notes.md | birta -

Export a self-contained static bundle (crawls relative .md links, copies assets):

birta --static README.md                 # writes a temp birta-README/ folder and opens it
birta --static --out ./site README.md    # writes the bundle to ./site

The bundle mirrors your source tree as .html files with relative links, so it works offline and can be zipped or moved.

List all available themes:

birta --list-themes

Run birta --help for the full flag reference.

 

Themes

Bundled: github catppuccin dracula gruvbox monokai night-owl nord one-dark rose-pine synthwave-84 tokyo-night

Themes with both light and dark variants get a toggle in the header. Switch themes at runtime from the dropdown — no restart needed.

Custom themes go in ~/.config/birta/themes/ as TOML files. See the bundled themes for the format.

 

Configuration

Persistent settings live in ~/.config/birta/config.toml:

port = 3000

[theme]
name = "catppuccin"

[font]
body = "Georgia, serif"
mono = "JetBrains Mono, monospace"

[keybindings]
toggle_reading = "r"       # reading mode
toggle_dark = "d"          # light/dark toggle
toggle_raw = "u"           # preview/raw toggle
focus_theme = "t"          # open theme picker

All settings can be overridden with CLI flags. Keybindings support modifiers: --bind toggle_raw=Alt+u. Run birta --help for the complete list.

 

Neovim

The Neovim plugin lives in a separate repo: birta.nvim

-- lazy.nvim
{
  "hugvit/birta.nvim",
  cmd = { "Birta" },
  opts = {
    theme = "catppuccin",
  },
}

Most flags can be accessed through the plugin's config.  

License

MIT