Vantage 🔭

A beautiful local Markdown viewer with live reload and Git awareness.

Website · GitHub · Issues

Vantage renders your Markdown files the way GitHub does — locally, instantly, with live reload as you edit. Point it at one directory or several, and browse your docs in a polished web UI with file tree navigation, Mermaid diagrams, commit history, and diffs.

Vantage ships as a single Go binary with an embedded React frontend — no runtime dependencies, no background services to babysit. Built for developers who write docs alongside code, and especially useful for reviewing LLM-generated Markdown output in real time.

Platform: Linux and macOS are fully supported. Windows is not supported.

Install

go install

go install github.com/mschulkind-oss/vantage/cmd/vantage@latest

This installs a vantage binary to your $GOBIN (typically ~/go/bin). Make sure it's on your PATH.

Homebrew (recommended)

brew install mschulkind-oss/tap/vantage

From source

git clone https://github.com/mschulkind-oss/vantage
cd vantage
mise install               # installs Go 1.26, Node 22, just
just build                 # produces ./vantage

The resulting ./vantage binary embeds the compiled frontend, so it's fully self-contained.

🚀 Quick Start

Single Directory

Point Vantage at any directory containing Markdown files — or a specific file:

vantage ~/Documents/notes          # open a directory
vantage ~/Documents/notes/intro.md # open a specific file

The server starts, your default browser opens to the file (or directory root), and the sidebar focuses on the parent directory of what you opened. Pass --no-open to suppress the browser launch.

Point it at the directory holding your git clones and each clone becomes its own project, exactly as the daemon's source_dirs would make them, plus one project for any Markdown outside them (--one-project keeps them all together). To keep the clones served in the background:

vantage ~/code                                   # one project per clone
vantage install-service --source-dir ~/code      # the clones, as a login service

Multiple Directories (Daemon Mode)

To serve several directories at once, create a config and run the daemon:

# Generate a config file
vantage init-config

# Edit it
$EDITOR ~/.config/vantage/config.toml

# Start the daemon
vantage daemon

✨ Features

• GitHub-Style Rendering — Full GitHub Flavored Markdown with syntax highlighting, tables, task lists, and footnotes
• Math & Diagrams — KaTeX math rendering and inline Mermaid diagrams from fenced code blocks
• Live Reload — Files update instantly in the browser via WebSocket when modified on disk
• Git Integration — View commit history, diffs, working-tree changes, file status, and recent changes for any file
• Review Mode — Inline comments with tracked agent responses (delivered via .vantage/inbox files or pasted into the panel) for collaborative review
• Multi-Repo Mode — Serve multiple directories from a single daemon, each accessible by name
• Source Directory Auto-Discovery — Point at parent directories to automatically find and add all git repos
• File Tree Navigation — Lazy-loaded sidebar with directory expansion
• Frontmatter Support — Displays YAML and TOML frontmatter as a clean metadata table
• Agent CLI — vantage-check: a standalone binary that prints Vantage's Markdown conventions and verifies that a document really renders
• Static Site Export — Build a standalone static site from a directory of Markdown
• Dark Mode — Toggle with Shift+D, persisted across sessions
• Color Themes — Slate (the built-in look) plus Catppuccin, Gruvbox, Lila, Nord, Solarized and Tokyo Night, or your own palette as one CSS file in ~/.config/vantage/themes/ (guide)
• Keyboard Shortcuts — Quick file picker with t, fuzzy search, keyboard navigation
• Performance Diagnostics — Built-in perf-report command for anonymized timing data
• Login Service — Run in the background from login: a systemd user unit on Linux, a launchd agent on macOS

🤝 Works well with

matt-craft is a set of skills for writing the kinds of documents Vantage is built to read: design notes that carry their open questions, roadmaps, research rounds, user stories — and one skill aimed squarely at Vantage's own Markdown conventions. Same author as this one, which is not a coincidence.

You do not need it. Vantage renders the Markdown you already write, in whatever style you already write it. But if you would rather not invent a house style for design docs, there is one sitting right there.

⚙️ Configuration

The config file lives at ~/.config/vantage/config.toml on Linux and macOS alike ($XDG_CONFIG_HOME/vantage/config.toml when that is set). Generate one with:

vantage init-config

Example Config

# Server settings
host = "127.0.0.1"
port = 8000

# Auto-discover git repos under these directories, re-scanned every 30s so a
# new clone is served — and a deleted one dropped — without a restart
source_dirs = ["~/code", "~/projects"]

# Or list repos explicitly (both methods can be combined)
[[repos]]
name = "notes"
path = "~/Documents/notes"

[[repos]]
name = "work-docs"
path = "~/work/documentation"

Each repo is accessible at http://localhost:8000/{name}/ — or whatever port Vantage printed on startup, if 8000 was taken (only the default port falls forward; see the note under --port below).

Configuration Reference

Excluded Directories

By default, Vantage hides common build and dependency directories from the sidebar, file picker, and recent files — for example node_modules, dist, build, .cache, .git, .hg, and .svn.

Override this in your config:

exclude_dirs = ["node_modules", "vendor", "dist"]

🔧 Service Management

Vantage can run as a per-user background service that starts on login — a systemd user unit on Linux, a launchd agent on macOS. One command writes either:

vantage install-service

It writes the service definition and prints the commands that load it; it never activates anything for you.

Linux (systemd)

install-service creates ~/.config/systemd/user/vantage.service.

# Enable and start
systemctl --user daemon-reload
systemctl --user enable vantage
systemctl --user start vantage

# Check status
systemctl --user status vantage

# View logs
journalctl --user -u vantage -f

# Restart after config changes
systemctl --user restart vantage

# Stop the service
systemctl --user stop vantage

User services stop when you log out. To keep Vantage running past logout:

loginctl enable-linger $USER

macOS (launchd)

install-service creates ~/Library/LaunchAgents/io.github.mschulkind-oss.vantage.plist.

# Load and start — now, and at every login
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/io.github.mschulkind-oss.vantage.plist

# Check status
launchctl print gui/$(id -u)/io.github.mschulkind-oss.vantage

# View logs (launchd has no journal; the agent writes to a file)
tail -f ~/Library/Logs/vantage.log

# Restart after config changes
launchctl kickstart -k gui/$(id -u)/io.github.mschulkind-oss.vantage

# Stop and unload
launchctl bootout gui/$(id -u)/io.github.mschulkind-oss.vantage

kickstart restarts the job from the plist launchd read at bootstrap time, not from the file on disk — so after re-running install-service, bootout and bootstrap again. See Daemon Mode for the rest.

🖥️ CLI Reference

The command is vantage.

vantage [PATH]                      # Serve a dir or file, auto-open browser
vantage serve [PATH] [flags]        # Same as above, with explicit flags
vantage daemon [-c config.toml]     # Serve multiple directories from config
vantage init-config                 # Generate example config file
vantage install-service             # Install a login service (systemd / launchd)
vantage install-service --source-dir DIR  # Add DIR's clones to the config, install and start it
vantage build PATH -o OUTPUT        # Build a static site
vantage perf-report [--url]         # Performance diagnostics from a running instance

serve flags

🔌 API

Vantage exposes a REST API for programmatic access under /api.

Single-Repo Endpoints

Multi-Repo Endpoints

In daemon mode, endpoints are prefixed with /api/r/{repo}/:

Utility Endpoints

🛠️ Development

Run the quality gate with just check (gofmt, go vet, staticcheck, go test, plus frontend lint, tsc, and vitest). See docs/development.md for more on building, testing, and contributing to Vantage.

📄 License

Apache 2.0 — see LICENSE.