birta

from the Icelandic word for brighten and publish

_{Live-reloading preview in your browser with GitHub-style rendering}

   

 

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

cargo install birta

Homebrew

brew install hugvit/tap/birta

From source

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