GitHub go.mod Go version GitHub tag (latest SemVer) Unit-Tests

English | 简体中文

MarkView is a zero-config Markdown preview server powered by Go and Bun.

It focuses on local documentation reading: fast startup, live updates, clear sidebar navigation, and solid support for Mermaid diagrams and code highlighting.

MarkView

• 🚀 Zero Config: run it in any directory, open README.md by default, or show a directory listing when it is missing
• ⚡ Single-binary delivery: the Go binary embeds web/dist and the HTML template, so no separate static deployment is required
• 🔄 Live Reload: watches Markdown changes and updates the page through SSE
• 🔍 Full-text search:
  • Files tree file name search
  • Support for searching document content, including headers, code blocks, etc.
• 🧭 Dual sidebar navigation:
  • Files tree with expandable directories and current-file highlighting
  • On This Page table of contents with scroll spy
• 🔁 Inline navigation:
  • file tree clicks do not trigger full page reloads
  • in-document internal Markdown links are handled inline
  • browser back/forward navigation is supported
• 📖 Split preview: hover over internal Markdown links to reveal a preview button, click to open the target document in a side-by-side panel
• 🎨 Rich rendering:
  • GFM (GitHub Flavored Markdown)
  • Image fullscreen viewer
  • highlight.js syntax highlighting
  • mermaid.js rendering with source toggle and fullscreen viewer
• ⚙️ Reading preferences:
  • page width presets
  • font size increase, decrease, and reset
  • settings persisted in localStorage
• 📱 Responsive layout: sidebar-first reading on desktop, single-column layout on mobile

go install github.com/inhere/markview@latest

Install by Eget:

eget install inhere/markview

Download and run markview:

# Preview the current directory (optional port; unset uses automatic project port)
markview [-p PORT]
# Preview a specific directory (default is current directory)
markview "path/to/docs"
# Preview a specific directory and set the default entry file (default entry is `README.md`)
markview "path/to/docs" "intro.md"

When no port is specified, MarkView automatically chooses and remembers a project port, preferring 6100 when available.

Example documents are available in example/.

You can adjust the port and default entry via .env / environment variables / options:

Using environment variables:

MKVIEW_PORT=8080 markview
MKVIEW_ENTRY=guide.md markview
MKVIEW_INCLUDE_DIR=.docs markview
MKVIEW_PREVIEW_EXTS=append:.html,.ini markview
MKVIEW_IFRAME_HOSTS=*.hyy.preview.test markview

$env:MKVIEW_PORT = "8080"; markview
$env:MKVIEW_ENTRY = "guide.md"; markview
$env:MKVIEW_INCLUDE_DIR = ".docs"; markview
$env:MKVIEW_PREVIEW_EXTS = "append:.html,.ini"; markview
$env:MKVIEW_IFRAME_HOSTS = "*.hyy.preview.test"; markview

Using project config, create markview.local.json, .markview.json, or markview.json in the project root:

{
 "server": {
 "include_dir": ".docs,.wiki"
 }
}

See docs/markview-json-example.md for a complete markview.json example.

server.include_dir and MKVIEW_INCLUDE_DIR allow selected skipped directories, including dot-prefixed documentation directories, to appear in the file tree. .git and node_modules are always skipped.

ui.preview_exts and MKVIEW_PREVIEW_EXTS configure file extensions opened in the preview panel. ui.iframe_hosts and MKVIEW_IFRAME_HOSTS configure external hosts that may open in the iframe preview panel; suffix rules such as *.hyy.preview.test or .hyy.preview.test match any subdomain.

Using CLI options:

markview -p 6543
markview . "guide.md"

• Go 1.25+
• Bun 1.0+

markview/
├── web/ # Frontend source, template, and build output
│ ├── src/
│ │ ├── app.ts # Page lifecycle, navigation, orchestration
│ │ ├── sidebar.ts # File tree and TOC logic
│ │ ├── mermaid.ts # Mermaid enhancement and fullscreen behavior
│ │ ├── link-preview.ts # Split preview for internal Markdown links
│ │ ├── preferences.ts # Persisted reading preferences
│ │ └── live-status.ts # SSE connection status handling
│ ├── template.html # Main page template and CSS
│ ├── dist/ # Bun build output embedded by Go
│ └── package.json
├── main.go # Go server entrypoint
├── handlers.go # Cache header and handler helpers
├── example/ # Example Markdown documents
└── README.md

1. Install web dependencies and build:

cd web
bun install
bun run build

This generates web/dist/ and also copies:

• highlight.css
• logo.svg
• favicon.svg

2. Build the backend:

cd ..
go build --ldflags "-w -s" -o markview.exe
# Or install to GOPATH/bin
go install -ldflags "-s -w" .

You can also use the provided Makefile:

make web
make build
make run

Useful verification commands:

go test ./...
cd web && bun test ./src/*.test.ts
cd web && bun run build

go:embed packages both web/template.html and web/dist/ into the final binary.

MIT