{"id":47679527,"url":"https://github.com/mschulkind-oss/vantage","last_synced_at":"2026-05-31T04:00:33.104Z","repository":{"id":341138654,"uuid":"1167929414","full_name":"mschulkind-oss/vantage","owner":"mschulkind-oss","description":"A beautiful local Markdown viewer with live reload and Git awareness","archived":false,"fork":false,"pushed_at":"2026-05-25T03:23:26.000Z","size":1496,"stargazers_count":8,"open_issues_count":5,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-25T03:25:37.673Z","etag":null,"topics":["developer-tools","git","live-reload","markdown","mermaid","viewer"],"latest_commit_sha":null,"homepage":"https://vantageapp.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mschulkind-oss.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-26T20:50:23.000Z","updated_at":"2026-05-25T03:23:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mschulkind-oss/vantage","commit_stats":null,"previous_names":["mschulkind/vantage","mschulkind-oss/vantage"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/mschulkind-oss/vantage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mschulkind-oss%2Fvantage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mschulkind-oss%2Fvantage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mschulkind-oss%2Fvantage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mschulkind-oss%2Fvantage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mschulkind-oss","download_url":"https://codeload.github.com/mschulkind-oss/vantage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mschulkind-oss%2Fvantage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33718446,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["developer-tools","git","live-reload","markdown","mermaid","viewer"],"created_at":"2026-04-02T13:54:59.209Z","updated_at":"2026-05-31T04:00:33.098Z","avatar_url":"https://github.com/mschulkind-oss.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vantage 🔭\n\n[![CI](https://github.com/mschulkind-oss/vantage/actions/workflows/ci.yml/badge.svg)](https://github.com/mschulkind-oss/vantage/actions/workflows/ci.yml)\n\n**A beautiful local Markdown viewer with live reload and Git awareness.**\n\n[Website](https://vantageapp.dev) · [GitHub](https://github.com/mschulkind-oss/vantage) · [Issues](https://github.com/mschulkind-oss/vantage/issues)\n\n![Vantage screenshot](docs/screenshot.png)\n\nVantage 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.\n\nVantage 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.\n\n\u003e **Platform:** Linux and macOS are fully supported. Windows is not supported.\n\n---\n\n## Install\n\n### go install\n\n```bash\ngo install github.com/mschulkind-oss/vantage/cmd/vantage@latest\n```\n\nThis installs a `vantage` binary to your `$GOBIN` (typically `~/go/bin`). Make sure it's on your `PATH`.\n\n### Homebrew (recommended)\n\n```bash\nbrew install mschulkind-oss/tap/vantage\n```\n\n### From source\n\n```bash\ngit clone https://github.com/mschulkind-oss/vantage\ncd vantage\nmise install               # installs Go 1.26, Node 22, just\njust build                 # produces ./vantage\n```\n\nThe resulting `./vantage` binary embeds the compiled frontend, so it's fully self-contained.\n\n---\n\n## 🚀 Quick Start\n\n### Single Directory\n\nPoint Vantage at any directory containing Markdown files — or a specific file:\n\n```bash\nvantage ~/Documents/notes          # open a directory\nvantage ~/Documents/notes/intro.md # open a specific file\n```\n\nThe 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.\n\n### Multiple Directories (Daemon Mode)\n\nTo serve several directories at once, create a config and run the daemon:\n\n```bash\n# Generate a config file\nvantage init-config\n\n# Edit it\n$EDITOR ~/.config/vantage/config.toml\n\n# Start the daemon\nvantage daemon\n```\n\n---\n\n## ✨ Features\n\n- **GitHub-Style Rendering** — Full GitHub Flavored Markdown with syntax highlighting, tables, task lists, and footnotes\n- **Math \u0026 Diagrams** — KaTeX math rendering and inline Mermaid diagrams from fenced code blocks\n- **Live Reload** — Files update instantly in the browser via WebSocket when modified on disk\n- **Git Integration** — View commit history, diffs, working-tree changes, file status, and recent changes for any file\n- **Review Mode** — Inline comments, snapshots, and agent changelog reactions for collaborative review\n- **Multi-Repo Mode** — Serve multiple directories from a single daemon, each accessible by name\n- **Source Directory Auto-Discovery** — Point at parent directories to automatically find and add all git repos\n- **File Tree Navigation** — Lazy-loaded sidebar with directory expansion\n- **Frontmatter Support** — Displays YAML and TOML frontmatter as a clean metadata table\n- **Static Site Export** — Build a standalone static site from a directory of Markdown\n- **Dark Mode** — Toggle with Shift+D, persisted across sessions\n- **Keyboard Shortcuts** — Quick file picker with `t`, fuzzy search, keyboard navigation\n- **Performance Diagnostics** — Built-in `perf-report` command for anonymized timing data\n- **systemd Service** (Linux) — Run as a background service that starts on login\n\n---\n\n## ⚙️ Configuration\n\nThe config file lives at `~/.config/vantage/config.toml`. Generate one with:\n\n```bash\nvantage init-config\n```\n\n### Example Config\n\n```toml\n# Server settings\nhost = \"127.0.0.1\"\nport = 8000\n\n# Auto-discover git repos under these directories\nsource_dirs = [\"~/code\", \"~/projects\"]\n\n# Or list repos explicitly (both methods can be combined)\n[[repos]]\nname = \"notes\"\npath = \"~/Documents/notes\"\n\n[[repos]]\nname = \"work-docs\"\npath = \"~/work/documentation\"\n```\n\nEach repo is accessible at `http://localhost:8000/{name}/`.\n\n### Configuration Reference\n\n| Key                          | Type             | Default            | Description                                      |\n| ---------------------------- | ---------------- | ------------------ | ------------------------------------------------ |\n| `host`                       | string           | `\"127.0.0.1\"`      | Server bind address                              |\n| `port`                       | integer          | `8000`             | Server port                                      |\n| `source_dirs`                | array of strings | `[]`               | Parent directories to scan for git repos         |\n| `repos[].name`               | string           | _required_         | Display name and URL slug for the directory      |\n| `repos[].path`               | string           | _required_         | Path to directory (supports `~`)                 |\n| `repos[].allowed_read_roots` | array of strings | `[]`               | Additional directories this repo may read        |\n| `exclude_dirs`               | array of strings | _(see below)_      | Directories to hide from file listings            |\n| `show_hidden`                | boolean          | `true`             | Show dotfiles in sidebar                          |\n| `walk_max_depth`             | integer or null  | `null` (unlimited) | Max directory depth for untracked file discovery  |\n| `walk_timeout`               | float            | `30.0`             | Timeout (seconds) for git ls-files subprocess     |\n| `use_ignore_files`           | boolean          | `true`             | Honor `.gitignore` and ignore files during walks  |\n| `disable_whats_new`          | boolean          | `false`            | Hide the \"What's New\" panel                       |\n| `log_level`                  | string           | `\"info\"`           | Logging verbosity                                 |\n\n### Excluded Directories\n\nBy 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`.\n\nOverride this in your config:\n\n```toml\nexclude_dirs = [\"node_modules\", \"vendor\", \"dist\"]\n```\n\n---\n\n## 🔧 Service Management (Linux)\n\nOn Linux, Vantage can run as a systemd user service that starts automatically on login. On macOS, run `vantage` directly or wrap it in a `launchd` agent yourself.\n\n### Install the Service\n\n```bash\nvantage install-service\n```\n\n### Enable and Start\n\n```bash\nsystemctl --user daemon-reload\nsystemctl --user enable vantage\nsystemctl --user start vantage\n```\n\n### Common Commands\n\n```bash\n# Check status\nsystemctl --user status vantage\n\n# View logs\njournalctl --user -u vantage -f\n\n# Restart after config changes\nsystemctl --user restart vantage\n\n# Stop the service\nsystemctl --user stop vantage\n```\n\n### Keep Running After Logout\n\nBy default, user services stop when you log out. To keep Vantage running:\n\n```bash\nloginctl enable-linger $USER\n```\n\n---\n\n## 🖥️ CLI Reference\n\nThe command is `vantage`.\n\n```\nvantage [PATH]                      # Serve a dir or file, auto-open browser\nvantage serve [PATH] [flags]        # Same as above, with explicit flags\nvantage daemon [-c config.toml]     # Serve multiple directories from config\nvantage init-config                 # Generate example config file\nvantage install-service             # Install systemd user service (Linux only)\nvantage build PATH -o OUTPUT        # Build a static site\nvantage perf-report [--url]         # Performance diagnostics from a running instance\n```\n\n### `serve` flags\n\n| Flag                  | Description                                          |\n| --------------------- | ---------------------------------------------------- |\n| `--host`              | Bind address (default `127.0.0.1`)                   |\n| `--port`              | Server port (default `8000`)                         |\n| `--no-open`           | Don't open the browser on start                      |\n| `--show-hidden`       | Show dotfiles in the sidebar                         |\n| `--exclude-dirs`      | Directories to hide from file listings               |\n| `--use-ignore-files`  | Honor `.gitignore` and ignore files during walks     |\n| `--walk-max-depth`    | Max directory depth for untracked file discovery     |\n| `--walk-timeout`      | Timeout (seconds) for git ls-files subprocess        |\n\n---\n\n## 🔌 API\n\nVantage exposes a REST API for programmatic access under `/api`.\n\n### Single-Repo Endpoints\n\n| Endpoint                                    | Description                          |\n| ------------------------------------------- | ------------------------------------ |\n| `GET /api/tree?path=.`                      | File tree listing                    |\n| `GET /api/content?path=file.md`             | File content                         |\n| `GET /api/files`                            | List all Markdown files              |\n| `GET /api/files/all`                        | List all files                       |\n| `GET /api/recent/all`                       | Recently accessed files              |\n| `GET /api/info`                             | Repository metadata                  |\n| `GET /api/git/history?path=file.md`         | Commit history                       |\n| `GET /api/git/diff?path=file.md\u0026commit=SHA` | Diff for a commit                    |\n| `GET /api/git/diff/working?path=file.md`    | Uncommitted changes diff             |\n| `GET /api/git/status?path=file.md`          | File status (modified, committed)    |\n| `GET /api/git/recent?limit=20`              | Recently changed files               |\n| `GET /api/review`                           | Read review comments and snapshots   |\n| `PUT /api/review`                           | Create or update review data         |\n| `DELETE /api/review`                        | Remove review data                   |\n\n### Multi-Repo Endpoints\n\nIn daemon mode, endpoints are prefixed with `/api/r/{repo}/`:\n\n| Endpoint                                 | Description                   |\n| ---------------------------------------- | ----------------------------- |\n| `GET /api/repos`                         | List configured repositories  |\n| `GET /api/r/{repo}/tree?path=.`          | File tree for a repo          |\n| `GET /api/r/{repo}/content?path=file.md` | File content for a repo       |\n| _(all single-repo endpoints above)_      | Prefixed with `/api/r/{repo}` |\n\n### Utility Endpoints\n\n| Endpoint                    | Description                             |\n| --------------------------- | --------------------------------------- |\n| `GET /api/health`           | Health check                            |\n| `GET /api/version`          | Server version info                     |\n| `GET /api/perf/diagnostics` | Performance diagnostics (anonymized)    |\n| `POST /api/perf/reset`      | Reset performance counters              |\n| `WS /ws`                    | WebSocket for live reload notifications |\n\n---\n\n## 🛠️ Development\n\nRun the quality gate with `just check` (gofmt, go vet, staticcheck, go test, plus frontend lint, tsc, and vitest). See [docs/development.md](docs/development.md) for more on building, testing, and contributing to Vantage.\n\n---\n\n## 📄 License\n\nApache 2.0 — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmschulkind-oss%2Fvantage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmschulkind-oss%2Fvantage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmschulkind-oss%2Fvantage/lists"}