Dev In The Mountain Header
A Developer In The mountains having fun

katdown

← The kat Suite · GitHub

A markdown viewer (GUI), built with Go and Wails.

Like a lot of developers I'm used to vim-style keybindings and might even like terminal editors, but whoever you are, I bet you already have a favorite editor. So katdown doesn't try to be an editor. It's just a really good markdown viewer: press e to open the file in your own editor, and katdown re-renders every time you save.

Features

  • GitHub-flavored markdown: tables, task lists, strikethrough, autolinks and footnotes
  • Syntax highlighting with any chroma style, separate for dark and light themes
  • Mermaid diagrams and KaTeX math ($…$ inline, $$…$$ for display). Both are bundled, so everything renders offline
  • Live reload: the view re-renders whenever the file is saved
  • YAML front matter shown as a collapsible table instead of raw text
  • Follows links: web links open in your browser, relative .md links open in katdown (including other.md#heading), and H / L go back and forward
  • Table of contents as an overlay or a sidebar that stays open while you read
  • Search with vim-style smartcase, n / N for next / previous
  • Highlight patterns: anything in curly braces is highlighted by default (good for templates and placeholders), and you can add your own regular expressions, like \bTODO\b
  • Safe by default: raw HTML is sanitized, so common tags like <details>, <kbd> and <sub> work but scripts and event handlers are removed. Start with -html to allow everything for files you trust
  • A : command window with completion: open files, jump to headings, list recent files, change settings for the session, edit the config
  • Windows builds, plus a katdown-win helper for WSL users

Usage

katdown [-html] [-makeconfig] [-makestyle] [-updateconfig] [file.md]
  • katdown notes.md opens a file; with no file it shows a file picker
  • katdown -makeconfig writes ~/.config/katdown/config.toml with every default
  • katdown -updateconfig adds settings your config is missing as commented-out lines with explanations
  • katdown -makestyle writes the default style.css so you can restyle everything
  • katdown-win notes.md (from WSL) opens the file in the Windows version

Keys

KeyAction
j / kscroll down / up
d / u, Space / bhalf page / full page
gg / Gtop / bottom
/, n / Nsearch, next / previous match
eedit the file in your editor
Ctrl-oopen another file
H / Lback / forward between files
ttable of contents
]] / [[next / previous heading
Ctrl-+ / Ctrl-- / Ctrl-0zoom text
:command window
?key help
qquit

Settings

Everything lives in a simple config.toml; press Ctrl-r to apply changes.

toml
theme = "dark"                 # dark | light | system

[font]
body = "Inter Variable"        # any installed font
mono = "JetBrains Mono Variable"
size = 16

[layout]
width = "46rem"                # max width of the text column

[code]
dark = "tokyonight-night"      # any chroma style
light = "github"

[editor]
command = ""                   # e.g. "code --wait"; empty uses $VISUAL

[toc]
style = "overlay"              # or "sidebar"

If a style.css exists in the config folder it replaces the built-in style. The palette is a set of CSS variables at the top (Mermaid diagrams use them too), so changing a few colors is easy.

Install

katdown is built from source. You need Go 1.26+, Node and npm, and on Linux the GTK 3 and WebKit dev packages (sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev on Ubuntu).

bash
go install -tags gtk3 github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0
git clone https://github.com/devinthemtn/katdown.git
cd katdown
wails3 task install            # or: task install

This puts katdown in ~/.local/bin and adds an app launcher entry. From WSL, wails3 task install-windows installs the Windows build with a Start Menu shortcut and an .md "Open with" entry, and wails3 task build-win-installer makes a standalone Windows installer.

Works well with

  • katNotes uses katdown as its default previewer
  • Any editor you like: vim, emacs, VS Code, Zed…
More places to find me
Mental Health
follow me on Mastodon