为什么做 mdview？ 在 AI 时代，我们每天都会收到一大堆 Markdown —— 任务书、研究笔记、Agent 输出、对话导出。我们只想安静地读这些文件，而不是打开笨重的 IDE、登录某个云端账户、或者装个浏览器扩展。市面上的 Markdown 查看器要么功能过剩（比如带 Git 集成要你 commit），要么过于简陋（一块无样式的纯文本）。

mdview 想做的，就是中间那条路：打开任意目录，舒服地读，切主题，看公式，全程不修改文件。一行命令启动，浏览器自动开，跑完 Ctrl+C 退出，干干净净。

特性一览

| | | |--|--| | 📂 目录树浏览，键盘导航 + 实时模糊过滤 + 一键刷新 | | | 📖 GFM Markdown + 代码高亮（highlight.js）+ HTML 净化（DOMPurify） | | | 🔢 LaTeX 公式（$...$ 行内 + $$...$$ 行间），KaTeX 渲染，可关闭 | | | 🧭 Mermaid 图表 —— ```mermaid 围栏自动渲染成内联 SVG（流程图 / 时序图 / 类图 / 甘特图 等），可在设置中关闭 | | | 📊 三线表（学术风），文字居中 | | | 🎨 主题配置化（JSON 文件），自带 4 套主题，可替换主题 | | | 🔠 字体设置：4 套预设 + 270+ 本机字体扫描 + 12–20px 字号 | | | ⌨️ 快捷键自定义（9 个动作 + 冲突检测） | | | ⚙️ 设置面板挂在左下角，简洁不打扰 | | | 🌗 自动暗色模式，跟随 OS | | | 🪟 系统级文件夹选择对话框（Windows / macOS / Linux 三端一致） | | | 💾 持久化：所有偏好都进 localStorage | |

安装

从 npm 安装（推荐）

# 不装全局，在当前目录直接跑：
npx @ap01lo/mdview

# 或全局装一次，以后任意地方都可以用：
npm install -g @ap01lo/mdview
mdview

要求 Node.js ≥ 18。

从源码安装

git clone https://github.com/Ap01lo/mdview.git
cd mdview
npm install
npm link          # 可选：注册全局 mdview 命令

环境要求

• Node.js ≥ 18
• 现代浏览器（Chromium / Firefox / Safari / Edge）

使用

mdview                       # 打开当前目录
mdview ./docs                # 打开子目录
mdview D:\projects\notes     # 打开绝对路径
mdview --port 8080           # 自定义端口（默认自动选）
mdview --theme serif-light   # 指定默认主题
mdview --no-open             # 不自动打开浏览器
mdview --host 0.0.0.0        # 绑定所有接口（局域网访问）
mdview --help                # 查看完整帮助

服务起来后，顶栏点 📂 按钮（或点当前路径文字）即可随时切换目录 —— mdview 会弹一个原生文件夹选择框，不用重启。

快捷键

| 键 | 动作 | |--|--| | Ctrl/⌘ + \\ | 收起 / 展开侧边栏 | | Ctrl/⌘ + K | 聚焦搜索框 | | Ctrl/⌘ + , | 打开设置 | | ↑ / ↓ | 上下移动 | | → / ← | 展开 / 折叠目录 | | Enter / Space | 打开文件 | | Tab / Shift+Tab | 焦点切换 | | Esc | 关闭设置 / 退出搜索 |

所有快捷键都可以在设置面板里重新绑定。

主题

主题是 themes/*.json 里的纯配置。每个文件定义一组 CSS 变量，mdview 启动时把它写入文档根节点：

{
  "name": "我的主题",
  "description": "在 GitHub 基础上微调",
  "vars": {
    "--bg": "#ffffff",
    "--fg": "#1f2328",
    "--accent": "#0969da",
    "--content-max": "720px",
    "--md-line-height": "1.75",
    "--md-table-top": "2px solid #1f2328",
    "--md-table-align": "center"
  }
}

往那个目录扔一个文件，下一次刷新就能在主题下拉里看到它，无需重启。

安全

• 文件访问严格限制在当前挂载的目录内
• 路径穿越攻击（..、绝对路径）一律返回 403
• 大于 5 MB 的文件返回 413
• 所有渲染到页面的 HTML 都过 DOMPurify 净化

项目结构

mdview/
├── bin/mdview.js          CLI 入口 + Express 服务
├── public/                SPA（HTML / CSS / JS / SVG 图标）
│   ├── index.html
│   ├── style.css
│   ├── app.js
│   └── favicon.svg
├── themes/                内置主题
│   ├── github-light.json
│   ├── github-dark.json
│   ├── serif-light.json
│   └── noir.json
├── package.json
├── LICENSE
└── README.md / README.zh.md

贡献

Issue 和 PR 都欢迎 —— 但请尽量保持改动单一目的，mdview 是个有意做得小而专的工具。

新增主题请直接在 themes/ 下放 JSON，记得在 vars 里至少包含 --bg 和 --fg，其它变量都有默认值。

发版步骤见 PUBLISHING.md。

协议

MIT —— 见 LICENSE。