DocView

Beautiful document viewer for Markdown, YAML, JSON, config files, and images — served locally in your browser.

Try it in 10 seconds

No install needed. Open your terminal, cd into any folder with documents, and run:

npx github:simota/docview

Your browser opens at http://localhost:4000 and the folder becomes a browsable document site. Press Ctrl + C to stop.

First time opening a terminal? You only need to do this once.

• macOS — Press ⌘ + Space, type Terminal, press Enter.
• Windows — Press the Windows key, type PowerShell, press Enter.
• Linux — Press Ctrl + Alt + T (most distros), or search for Terminal in your apps.

Then install Node.js 20.19+ (the LTS button is the safe choice), close and reopen the terminal, and run the command above.

Try it on a specific folder or file

npx github:simota/docview ./docs # view a folder
npx github:simota/docview README.md # open a single file

Does it work? — quick verification

OS	What to expect
macOS	Your default browser opens at http://localhost:4000 with a file tree on the left.
Windows	Edge (or your default browser) opens at http://localhost:4000 with a file tree on the left.
Linux	Your default browser opens at http://localhost:4000 with a file tree on the left.

If the browser doesn't open, copy http://localhost:4000 into any browser — it works the same way.

Features

• Markdown rendering — full CommonMark support with GitHub Flavored Markdown, footnotes, definition lists, subscript/superscript, emoji, and front matter
• Marp slides — Markdown files with marp: true front matter are presented as faithful Marp slides (default / gaia / uncover themes, paginate / header / footer / _class directives) via the toolbar Slides button or Cmd/Ctrl + Shift + S
• Mermaid diagrams — flowcharts, sequence diagrams, ER diagrams, and more rendered inline
• KaTeX math — inline and block LaTeX math expressions
• GitHub Alerts — [!NOTE], [!WARNING], [!TIP], [!IMPORTANT], [!CAUTION] callout blocks
• YAML / JSON tree views — structured, collapsible tree rendering for data files
• CSV / JSONL tables — sortable tables with a row-number column; jump to any row via the "行へ移動" toolbar input or a &line=N deep link
• HTML view — renders .html / .htm files in a sandboxed iframe (Preview / Source toggle). Scripts are disabled by default and can be enabled per-file via the toolbar toggle
• Crontab preview — parses crontab files into a table with human-readable schedule descriptions (Japanese / English toggle), a 24-hour timeline visualizing each job's daily run hours, a file-wide day-of-week × hour heatmap, an execution-frequency ranking, same-minute collision warnings, and the next execution times for each job (JST / UTC toggle)
• Config file highlighting — syntax highlighting for TOML, INI, .env, .conf, and similar formats
• Image display — renders PNG, JPEG, GIF, SVG, WebP, BMP, and ICO files directly in the browser
• Office / iWork file handling — lists Excel, PowerPoint, Numbers, Pages, and Keynote files, opens them in the OS default app from the local server, and keeps a download fallback for normal files. Browser WebViews cannot directly preview these formats without a conversion or app runtime
• PDF view — renders .pdf files with the browser's built-in PDF viewer (streamed with HTTP Range support), plus open-in-new-tab / open-in-app / download actions
• File tree with auto-reload — sidebar listing of all files in the served directory; changes are detected and reloaded automatically via file watching. Right-click an item for a context menu (copy path / file name / absolute path, open in split view)
• Dark / light theme — toggle between themes; preference is persisted
• Text size — adjust document text from 50% to 200% in 10% steps; preference is persisted
• Table of contents — auto-generated TOC sidebar from heading structure
• Search — full-text search across all files in the directory
• Tabs — open multiple files as tabs within a single session

Supported Formats

Category	Extensions
Markdown	.md.markdown.mdx.txt
Data	.json.yaml.yml
Config	.toml.ini.conf.env.cfg.properties
Crontab	.cron.crontab (and files named crontab)
Images	.png.jpg.jpeg.gif.svg.webp.bmp.ico
Office / iWork	.xls.xlsx.ppt.pptx.numbers.pages.key (listed, open in default app / download fallback for normal files; no direct WebView preview)
PDF	.pdf (browser built-in viewer in an iframe; open in new tab / default app / download)

Installation (optional)

npx github:simota/docview works without installing anything — that is the recommended way for most people. Install globally only if you use DocView every day and want a shorter command.

macOS / Linux

npm install -g github:simota/docview

Seeing EACCES / permission errors? Don't use sudo. Either stick with npx github:simota/docview (no install needed) or configure npm to use a user directory — npm's official guide walks through it.

Windows

npm install -g github:simota/docview

Run PowerShell as a regular user — admin mode is not required.

Verify the install

docview --version

If you see a version number, you're ready. Run docview inside any folder to start the viewer.

Usage

# View current directory
docview
# View a specific directory
docview ./docs
# Open a specific file
docview README.md
# Use the mdv alias with a custom port
mdv config.yaml -p 8080
# Don't auto-open the browser
docview ./docs --no-open

Options

Flag	Description	Default
-p, --port <port>	Port number	4000
--no-open	Don't auto-open the browser	—
-h, --help	Show help	—
-v, --version	Show version	—

Keyboard Shortcuts

Shortcut	Action
Cmd/Ctrl + P	Quick file switcher
Cmd/Ctrl + Shift + F	Full-text search
Cmd/Ctrl + B	Toggle sidebar
Cmd/Ctrl + E	Toggle table of contents
Cmd/Ctrl + Shift + E	Toggle theme (dark / light)
Cmd/Ctrl + Shift + S	Present as slides (Marp deck for marp: true files)
Cmd/Ctrl + = / - / 0	Increase / decrease / reset document text size
?	Show keyboard shortcut help
↑ / ↓	Navigate file list / search results

Custom CSS

Place a .docview.css file in the directory you are viewing (or any parent directory). DocView will automatically load it and apply your styles on top of the default theme.

Set --font-size-base to customize the document size used at the 100% Text size setting.

/* .docview.css */:root {
--font-size-base:16px;
}
.markdown-bodyh1 {
border-bottom:2px solid var(--color-accent);
}

Excluding files

DocView always skips common build, dependency, and cache directories (node_modules, dist, build, out, target, vendor, coverage, .next, .nuxt, .svelte-kit, .cache, __pycache__, …) and hidden directories from the file tree, search, backlinks, and live reload — so it stays usable on a real repository. Hidden files such as .env remain visible.

To exclude more, drop a .docviewignore file (gitignore-style) in the directory you are viewing. Changes take effect on the next request — no restart needed.

# .docviewignoregenerated # anydir/filenamed"generated"docs/legacy # aspecificpath,relativetotheservedroot*.min.js # globwithinapathsegmentfixtures/** # everythingunderfixtures/

.gitignore is intentionally not honored automatically, because files like .env are commonly git-ignored yet you usually want to view them here.

Tech Stack

• Vite — build tooling and dev server
• TypeScript — type-safe frontend code
• markdown-it — Markdown parser with plugin ecosystem
• Mermaid — diagram and chart rendering
• Marp Core — Markdown-driven slide rendering
• KaTeX — fast LaTeX math rendering
• highlight.js — syntax highlighting for code blocks and config files
• chokidar — file system watcher for live reload

License

MIT © 2026