mdview

README

mdview

A minimal markdown viewer. It opens a markdown file in a native window, lets you swap between colour themes, and that's it.

Built with Wails v3 and rendered with goldmark. The whole frontend is embedded in a single self contained binary, so go install gives you a working viewer with nothing else to set up.

Install

go install github.com/leaanthony/mdview@latest

That gives you the mdview command.

mdview uses the system webview, so it needs the same runtime pieces as any Wails v3 app:

• macOS: nothing extra, WebKit is built in.
• Windows: the WebView2 runtime (already present on Windows 11 and most Windows 10 machines).
• Linux: gtk3 and webkit2gtk development packages, and a C compiler (CGO_ENABLED=1). On Debian/Ubuntu: sudo apt install build-essential libgtk-3-dev libwebkit2gtk-4.1-dev.

Usage

mdview README.md

mdview [flags] <file.md>

Flags:
  -t, --theme <id>    initial theme id (see --list-themes)
      --list-themes   list available themes and exit
  -v, --version       print version and exit
  -h, --help          show this help

Pick a theme from the selector in the top right corner of the window, or press t to cycle through them. Your choice is remembered for next time. You can also set the starting theme from the command line:

mdview --theme dracula README.md

Themes

Six built in themes, light and dark. Prose and code are always styled together, so syntax highlighting matches whatever theme you pick.

id	name
github-light	GitHub Light
github-dark	GitHub Dark
dracula	Dracula
nord	Nord
solarized-light	Solarized Light
solarized-dark	Solarized Dark

When you have not picked a theme yet, mdview follows your system light or dark preference.

Use it as your default markdown viewer

go install is perfect for opening files from the terminal. To open .md files by double clicking them in your file manager, build a packaged application:

macOS

task package:darwin

This produces bin/mdview.app with the markdown file associations already declared. Move it to /Applications, then right click any .md file, choose Get Info, and set Open with to mdview (use Change All... to make it the default for every markdown file).

Building from source

task build      # build ./bin/mdview
task run        # run on the bundled sample document
task test       # run the tests

No Node, npm or bundler required. The frontend is plain HTML, CSS and a little vanilla JavaScript, all embedded at compile time.

How it works

• Markdown is rendered to HTML in Go with goldmark (GitHub Flavored Markdown: tables, task lists, strikethrough, footnotes and autolinks).
• Code blocks are highlighted with chroma using class based output, so changing theme restyles code instantly with no re-render.
• Each theme is a small set of CSS custom properties plus the matching chroma stylesheet. The structural stylesheet never changes.
• Raw HTML inside documents is left escaped, so viewing an untrusted file cannot run active content.

Licence

MIT. See LICENSE.

Documentation

Overview

Command mdview is a minimal markdown viewer. It opens a markdown file in a native window and lets you swap between colour themes. That's it.

Usage:

mdview [flags] <file.md>

It can also be registered as the system's default markdown viewer; a packaged build associates itself with .md and .markdown files.