Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

5 Commits
.github
.github
 
 
test
test
 
 
.gitignore
.gitignore
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
md-reader.html
md-reader.html
 
 
open-reader.command
open-reader.command
 
 
package.json
package.json
 
 

Repository files navigation

MD Reader

A zero-dependency, single-file HTML markdown reader.
TOC sidebar, full-text search, speed-reading panel, AI summary cards, XSS hardening.
Double-click to open. No install. No server. No cloud.

License Zero Dependencies Single File XSS Hardened Release Stars Tests Forks

English | 中文文档

Why this exists

AI tools and developers produce a lot of markdown — reports, analysis, documentation, retrospectives. But reading a 500-line .md file in a text editor is painful. Existing solutions either require an IDE (VS Code), cost money (Typora), or are heavyweight PKM systems (Obsidian).

MD Reader is one HTML file. You double-click it, drag in a markdown file, and get a clean, structured reading experience with table of contents, syntax highlighting, search, and themes. No install, no server, no cloud, no tracking.

Who is this for?

  • AI tool users — Claude, Cursor, and other AI tools generate long markdown reports; MD Reader makes them readable
  • Developers — read documentation without opening an IDE
  • Writers — preview markdown with a clean, distraction-free interface
  • Privacy-conscious users — zero network, zero tracking, zero cloud
  • Anyone with a .md file — double-click and read

Features

Reading

  • TOC sidebar — auto-generated from headings, click to jump, scroll-following highlight
  • Full-text search (Cmd/Ctrl+F) — highlight all matches with counter, jump between hits
  • Speed-reading panel — extracts headings, bold text, and key sentences into a digest view
  • Syntax-highlighted code — dark theme code blocks with monospace font
  • Image lightbox — click any image to enlarge, click overlay to close
  • Reading progress — status bar shows scroll %, remembers position per document
  • Back-to-top button — appears on scroll, smooth scroll to top

AI Summary Cards

  • Sidecar injection — place <filename>.md.summary.json next to your markdown file, and MD Reader displays a summary card at the top of the document
  • Schema: {tl_dr, key_points[], conclusions[], action_items[], generated_by, generated_at}
  • Zero LLM — the reader doesn't call any AI; summaries are generated by your AI tools and injected as JSON sidecars
  • Graceful degradation — if no sidecar exists, the deterministic speed-reading panel still works

Editing (V1.6)

  • Lightweight source editor — edit the markdown source directly in the reader
  • Live preview — apply changes to see re-rendered content instantly
  • Undo — revert to the original source at edit entry point
  • Download — Cmd/Ctrl+S to download the edited markdown
  • Read-only priority — original files on disk are never modified; edits live in memory
  • Auto-commit on switch — unsaved edits are committed to memory when switching documents

Security

  • XSS hardened — all HTML is escaped; javascript:, data:, and vbscript: (including Unicode / HTML-entity / percent-encoding camouflage) are stripped from links and images. CSP + no-referrer as defense in depth.
  • Code blocks — payloads inside code blocks are displayed as text, never executed
  • Tested — adversarial XSS samples (including protocol camouflage) are in the test suite
  • Zero network (reader chrome) — no CDN, no tracking, no analytics. The reader itself makes no requests. http(s) images inside a markdown file will still be fetched by the browser; referrers are stripped.

Themes

  • Light — clean white background
  • Dark — easy on the eyes at night
  • Eye-protection — warm sepia tone for extended reading

Quick Start

Option A: Direct (simplest)

git clone https://github.com/andersyin/md-reader.git
# macOS
open md-reader/md-reader.html
# Linux: xdg-open md-reader/md-reader.html

Drag and drop any .md file onto the browser window. This is the empty-state path the HTML itself describes.

Option B: Launcher (multi-file + AI sidecars)

git clone https://github.com/andersyin/md-reader.git
cd md-reader

# Open one or more markdown files (macOS `open`, Linux `xdg-open`)
bash open-reader.command report.md analysis.md notes.md

# Or double-click open-reader.command in Finder (uses last bundle; macOS)

The launcher bundles your markdown files (and AI summary sidecars) into a single _md_bundle.js, then opens the reader with all files pre-loaded. Switch between documents from the file list sidebar. Requires Python 3.

AI Summary Sidecar

Create report.md.summary.json next to report.md:

{
  "tl_dr": "Quarterly revenue grew 23% YoY, driven by SaaS expansion.",
  "key_points": [
    "SaaS revenue up 34%",
    "Churn down to 2.1%",
    "New enterprise accounts: 47"
  ],
  "conclusions": ["Sustainable growth trajectory for next 2 quarters"],
  "action_items": ["Prioritize enterprise onboarding", "Hire 2 CSMs"],
  "generated_by": "Claude",
  "generated_at": "2026-08-12 10:00"
}

When you open report.md via the launcher, the summary card appears at the top.

Comparison

Feature VS Code Preview Typora Obsidian MD Reader
Free Yes $15 $50/yr Yes
Zero install No (needs VS Code) No No Yes (one HTML file)
Zero dependency No No No Yes
XSS protection Partial N/A N/A Yes (tested)
AI summary cards No No No Yes
Speed-reading panel No No No Yes
Works offline Yes Yes Yes Yes
File size ~100MB ~80MB ~200MB 77KB

Keyboard Shortcuts

Key Action
j / ↓ Scroll down
k / ↑ Scroll up
g Scroll to top
G Scroll to bottom
t Toggle TOC sidebar
d Toggle speed-reading panel
Cmd/Ctrl+F Full-text search
Cmd/Ctrl+S Download edited markdown
Esc Exit edit mode / close search
[ Previous document
] Next document

Testing

npm install                    # installs playwright-core
node test/sanitize.mjs         # sanitizer + first-run/policy checks (no browser)
node test/generate-bundle.mjs  # generates test bundle from fixtures
node test/heartbeat_v16.mjs    # Playwright: 37 assertions across 3 phases

Or npm test (sanitize + bundle + heartbeat).

Test phases:

  • sanitize — safeUrl camouflage, XSS fixture render, CSP/zero-CDN, empty-state filename
  • Phase C — Edit mode: enter, modify, apply, undo, download, switch, keyboard shortcuts
  • Phase D — XSS resistance: fixture + edit-injected script/protocol/camouflage, code block safety
  • Phase E — Regression: zero-network chrome, search, HTML export, lightbox, status bar, back-to-top

File Structure

md-reader/
├── md-reader.html              # The reader (single file, ~77KB, zero deps)
├── open-reader.command         # Launcher (bundles files + opens reader)
├── LICENSE
├── CONTRIBUTING.md
├── package.json                # For running tests only
├── .github/workflows/test.yml  # sanitize + shellcheck + Playwright
├── test/
│   ├── sanitize.mjs            # Node-only sanitizer / policy checks
│   ├── heartbeat_v16.mjs       # Playwright suite (37 assertions)
│   ├── generate-bundle.mjs     # Generates test bundle from fixtures
│   ├── xss-sample.md           # XSS adversarial test fixture
│   ├── summary-demo.md         # AI summary sidecar demo
│   ├── summary-demo.md.summary.json
│   └── long-document.md        # Long document for scroll/layout testing
└── .gitignore

Requirements

  • Any modern browser (Chrome, Firefox, Safari, Edge)
  • For the launcher: Python 3; macOS open or Linux xdg-open
  • For testing: Node.js 22 + Chrome/Chromium

Limitations

  • Files are loaded into browser memory; very large files (>10MB) may be slow
  • Finder double-click of open-reader.command is macOS-only; on Linux use bash open-reader.command … or drag-and-drop
  • AI summaries are read-only from sidecar JSON; the reader does not generate summaries
  • Markdown may contain http(s) or file: URLs. The reader will load those images and follow links on click. Untrusted markdown can therefore cause network requests (tracking pixels) even though the reader chrome is offline.

Contributing

Contributions welcome! See CONTRIBUTING.md. Especially:

  • Cross-platform launchers (Windows .bat, Linux .sh)
  • Internationalization (English UI labels)
  • Additional markdown extensions (mermaid diagrams, math rendering)

License

MIT

中文文档

零依赖、单文件 HTML 的 Markdown 阅读器。支持大纲目录、全文搜索、速读面板、AI 摘要卡片、XSS 防护。双击即开，无需安装，无需联网。

特性

  • 大纲目录 — 自动生成，点击跳转，滚动跟随高亮
  • 全文搜索 — Cmd/Ctrl+F 高亮所有匹配，带计数器
  • 速读面板 — 提取标题、加粗、关键句，快速把握全文要点
  • AI 摘要卡片 — 同目录放 <文件名>.md.summary.json，正文顶部显示摘要卡
  • 代码高亮 — 暗色主题代码块，等宽字体
  • 图片灯箱 — 点击图片放大，点遮罩关闭
  • 阅读进度 — 状态栏显示滚动百分比，按文档记忆位置
  • 轻量编辑 — V1.6 新增，可直接编辑源码，实时预览，原文件只读不修改
  • 三主题 — 亮色 / 暗色 / 护眼
  • XSS 防护 — 所有 HTML 转义，危险协议（含 Unicode/实体/百分号伪装）拦截，CSP + 无 Referer
  • 阅读器零外网 — 无 CDN、无追踪、无分析。Markdown 里的 http(s) 图片仍会被浏览器拉取

快速开始

git clone https://github.com/andersyin/md-reader.git
cd md-reader

# 方式一：用启动器打开（推荐，支持多文件 + AI 摘要 sidecar）
bash open-reader.command 报告.md 分析.md

# 方式二：直接双击 md-reader.html，然后拖拽 md 文件到浏览器
open md-reader.html

AI 摘要 Sidecar

在 md 文件同目录放一个 <文件名>.md.summary.json：

{
  "tl_dr": "季度收入同比增长 23%，SaaS 扩张驱动。",
  "key_points": ["SaaS 收入增长 34%", "流失率降至 2.1%"],
  "conclusions": ["未来两季度可持续增长"],
  "action_items": ["优先企业客户 onboarding"],
  "generated_by": "Claude",
  "generated_at": "2026-08-12 10:00"
}

启动器会自动检测并注入，正文顶部显示摘要卡，文件列表显示「AI摘要」徽标。

测试

npm install                    # 安装 playwright-core
node test/sanitize.mjs         # 无浏览器的消毒 / 首启检查
node test/generate-bundle.mjs  # 从测试夹具生成 bundle
node test/heartbeat_v16.mjs    # 运行 37 项断言

You might also like

  • iphone-auto-backup — Auto-backup iPhone photos & videos on USB plug-in, EXIF date archiving, content-hash dedup
  • restic-backup-toolkit — 3-tier macOS backup: rsync mirror + restic cold backup + SHA256 audit

Star History

If this tool made your markdown readable, consider giving it a ⭐

About

Zero-dependency single-file HTML markdown reader. TOC, search, speed-reading panel, AI summary cards, XSS hardening. Double-click to open. No install. No server.

Topics

ai-summaryhtmlmacosmarkdownmarkdown-readerofflinesingle-filespeed-readingsyntax-highlightingtocxss-protectionzero-dependency

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages