markbrowse

markbrowse

A minimal markdown file viewer. Point it at any directory and it starts a web server that renders .md files as styled HTML, with a collapsible sidebar file tree for navigation.

Features

• Renders markdown files as HTML with GitHub-flavored styling (light + dark mode)
• Collapsible sidebar file tree for navigating the directory
• Uses directories' README.md or INDEX.md as the index page
• Falls back to a file listing when no index markdown is present
• Serves non-markdown files as-is (images, PDFs, etc.)
• Mermaid diagram rendering
• Wiki-style [[link]] syntax with file-tree resolution
• GitHub/Obsidian-style admonition callouts (> [!NOTE], > [!WARNING], etc.)
• Custom CSS support to override the built-in stylesheet
• Breadcrumb navigation on all pages
• Single binary, zero config

Install

go install github.com/anantshri/markbrowse@latest

Or build from source:

git clone https://github.com/anantshri/markbrowse.git
cd markbrowse
go build -o markbrowse .

Usage

# Serve current directory on port 8080
markbrowse

# Serve a specific directory
markbrowse /path/to/docs

# Custom port
markbrowse --port 3000

# Custom CSS (replaces built-in stylesheet entirely)
markbrowse --css ./my-theme.css

Open http://localhost:8080 in your browser. If the requested port is busy, markbrowse automatically falls back to the next free port (searching from 10000 upward) and logs the port it bound to.

How it works

Markdown rendering supports GFM features: tables, strikethrough, task lists, autolinks, heading anchors, mermaid diagrams, wiki links, and admonition callouts.

Flags

  --port int    Port to listen on (default 8080)
  --css path    Path to custom CSS file (replaces built-in stylesheet)
  --version     Print version and exit

Dependencies

• goldmark — markdown rendering with GFM extension
• goldmark/mermaid — mermaid diagram support
• goldmark/wikilink — [[wiki link]] parsing
• gm-alert-callouts — > [!NOTE] admonition callouts

Changelog

See CHANGELOG.md for release notes.

License

GPL-3.0