DocReader

DocReader 是一款基于浏览器的本地Markdown阅读工具，核心特性是“本地优先”——所有文件读取与渲染均在用户设备完成，无需上传服务器。用户只需将项目目录拖入浏览器或通过文件夹选择器加载，即可通过项目树导航、标签页管理和文档大纲快速浏览内容。

工具完整支持GitHub Flavored Markdown（GFM）、代码高亮、KaTeX数学公式及PlantUML图表渲染，并兼容常见源码、文本、图片与PDF文件。macOS提供一键启动脚本，Windows/Linux可通过npm手动运行，Node.js版本要求不低于22.13。

核心交互与文件同步机制

DocReader 的设计围绕“零配置即时阅读”展开，关键交互逻辑如下：

• 目录加载：支持点击“选择文件夹”或直接拖拽目录至页面；首次加载后浏览器会请求文件系统访问权限
• 导航体系：左侧项目树展示完整目录结构，顶部标签页保留已打开文档，支持⌘/Ctrl+K全局搜索文件、⌘/Ctrl+B切换目录面板、⌘/Ctrl+O更换根目录
• 实时同步：通过“选择文件夹”API打开的目录支持自动监听文件增删与内容变更；若使用拖拽方式加载则需手动刷新（工具栏保留刷新按钮作为兜底）
• 会话恢复：刷新页面时自动尝试恢复上次目录；若浏览器未持久化授权，仅需单次点击“继续打开”即可重新获取访问权，无需重复选择路径

这一设计平衡了便利性与安全性：自动同步提升连续阅读体验，而权限显式确认确保用户对数据访问始终保有控制权。

内容渲染能力与格式兼容性

DocReader 针对技术文档场景强化了多格式支持，覆盖开发者常见需求：

特别注意：PlantUML渲染依赖客户端WASM引擎，首次加载大型图表可能有短暂延迟；数学公式不支持MathJax扩展语法，复杂排版建议预检KaTeX兼容性。

部署方式与环境要求

macOS用户
双击启动DocReader.command即可自动安装依赖、启动服务并打开浏览器。终端窗口需保持开启状态，关闭即停止服务。该脚本内置Volta版本锁定，无需手动管理Node.js。

跨平台手动启动

npm install
npm run dev

访问http://localhost:3000。若未使用Volta，需确保Node.js ≥ 22.13；低版本可能导致ESM模块解析失败。生产环境可执行npm run build生成静态文件，但需注意：静态部署下文件系统API不可用，仅能通过拖拽加载目录且无自动同步功能。

浏览器兼容性
依赖File System Access API，推荐Chrome 86+、Edge 86+或Opera 72+。Firefox/Safari因API支持不完整，仅支持拖拽加载且无法自动同步，体验显著降级。

适用场景与局限性说明

最佳适用场景

• 本地技术文档库（如Git仓库docs目录）的快速查阅
• 包含数学公式与架构图的学术笔记离线阅读
• 多语言编码混合项目的统一查看（避免编辑器乱码）
• 临时接收他人Markdown资料时的免安装预览

明确局限

• 非编辑器：只读模式，不支持内容修改与保存
• 无协作功能：纯本地工具，不支持多人实时协同或评论
• 大目录性能：超万级文件的项目树初始化可能卡顿，建议按模块拆分目录
• PlantUML外部依赖：渲染需联网加载WASM模块（首次），完全离线环境需预缓存资源
• 移动端不支持：File System Access API仅限桌面浏览器，iOS/Android无法使用

对于需要编辑、版本控制或团队共享的场景，应搭配VS Code、Obsidian或Notion等工具；DocReader的定位是“轻量级本地文档浏览器”，核心价值在于零配置、隐私安全与多格式开箱即用。若仅需单文件预览，系统自带Markdown插件或在线编辑器更便捷；但当面对结构化项目文档时，其目录树+标签页+大纲的组合效率远超通用工具。