Markdown Reader

Markdown Reader 是一个轻量、本地运行的 VS Code Markdown 阅读插件。它从当前 .md 文件打开独立 Webview 阅读面板，提供更专注的阅读排版、文档大纲、主题切换、源码与阅读位置同步和快速编辑入口。

功能

• 从当前 Markdown 文件执行 Markdown Reader: 打开 Markdown 阅读器，或在 .md 文档编辑器中右键选择“打开 Markdown 阅读器”打开阅读视图。
• 渲染标题、段落、无序 / 有序列表、引用、表格、行内代码、代码块、强调、链接和本地图片。
• 使用 markdown-it 渲染复杂 Markdown，支持嵌套列表、只读任务列表 checkbox、含括号链接和水平分割线。
• 使用 highlight.js 为代码块提供语法高亮。
• 支持 mermaid 代码块的本地图表预览占位与语法错误回退，不加载远程资源。
• 支持行内 $...$ 与块级 $$...$$ 数学公式的轻量渲染。
• 代码块提供“复制”按钮，复制成功或失败会在阅读视图内反馈。
• 阅读视图显示字数、词数、标题数、代码块数量和预计阅读时间。
• 工具栏提供“复制目录”，可基于当前标题锚点复制 Markdown 目录片段。
• 工具栏提供“文档索引”，可扫描并过滤工作区 Markdown 文档后快速切换。
• 工具栏和命令面板提供显式 Markdown 格式化入口，格式化前确认，不会在保存时自动改写。
• 保存源 Markdown 文件后，已打开的阅读视图自动刷新。
• 保存刷新带有 400ms debounce，避免频繁保存时重复重渲染。
• 从标题生成可点击大纲，点击后稳定滚动到对应章节，立即同步高亮和地址 hash，并兼容中文、空格和特殊字符标题。
• 大纲区域提供“隐藏大纲 / 显示大纲”按钮，隐藏后正文区域自动扩大，并在阅读视图刷新后尽量恢复侧边栏状态。
• 阅读视图内置正文搜索，支持匹配高亮、当前结果强调、结果计数、上一个 / 下一个跳转和无结果提示。
• 支持浅色 / 深色阅读主题切换，并通过 VS Code 全局状态保存偏好。
• 支持通过 VS Code 设置调整阅读字体大小、正文行宽、行距和默认主题；阅读视图内手动切换主题后会优先使用手动偏好。
• 支持将当前阅读结果导出为离线 HTML，导出文件内联阅读样式和代码高亮样式，不包含 Webview 脚本、编辑区和源码定位按钮。
• 每个主要内容块提供“源码”按钮，可跳回 Markdown 源文件的相关行。
• 在已打开对应阅读视图时，Markdown 源码编辑器光标移动会防抖同步到同一文档的阅读块，并短暂高亮定位目标。
• - [ ]、- [x] 和 - [X] 任务列表会渲染为只读复选框，便于阅读待办状态；点击复选框不会写回源 Markdown。
• 提供编辑模式，可在阅读视图中直接修改整篇 Markdown 原文，保存后写回源文件并重新渲染。
• 保存前会比较打开编辑时的原文快照，若源文档已被外部更新，会拒绝覆盖并提示冲突。
• 编辑模式会将未保存草稿保存到当前 Webview state；刷新 Webview 后可恢复草稿并自动进入编辑态，取消、刷新或关闭前会在存在未保存改动时提示确认。

使用阅读视图

1. 打开任意 Markdown 文件，执行 Markdown Reader: 打开 Markdown 阅读器，或在编辑器中右键选择“打开 Markdown 阅读器”。
2. 点击左侧大纲标题可跳转到对应章节；跳转后当前大纲项会立即高亮，滚动阅读时高亮也会自动更新。
3. 点击工具栏的“隐藏大纲”可收起左侧侧边栏，正文区域会扩大；再次点击“显示大纲”可恢复，阅读视图会保存该显示状态。
4. 点击工具栏的“搜索”可打开搜索栏；输入关键词后正文匹配项会高亮，按 Enter 跳到下一个，按 Shift+Enter 跳到上一个，也可点击“上一个 / 下一个”按钮导航；点击“关闭”会清除所有高亮。
5. 在源码编辑器中移动光标时，阅读视图会滚动到最近的块级源码行映射位置；搜索高亮存在时仍基于块级 data-line 定位，编辑模式下不会滚动或抢占 textarea 焦点。
6. 点击“导出 HTML”可选择保存路径并导出离线阅读文件；如果取消保存对话框，不会写入文件或显示错误。
7. 任务列表中的复选框仅用于阅读展示；如需修改任务状态，请点击“编辑”或回到 Markdown 源文件修改原文。
8. 点击“编辑”进入 Markdown 原文编辑模式；进入编辑时会自动清除搜索高亮，输入内容会作为草稿保存在当前 Webview state 中。
9. 点击“取消”时，如果草稿已修改，会先确认是否放弃；刷新或关闭 Webview 前，如果存在未保存改动，会触发 VS Code / 浏览器默认离开提示。
10. 点击“保存”会写回当前源文件并刷新阅读内容；保存成功后会清理草稿，保存失败或发生外部更新冲突时会保留草稿，便于继续编辑或复制内容。
11. 点击“复制目录”可复制当前标题结构生成的 Markdown 目录；点击“文档索引”可过滤并切换工作区 Markdown 文档。
12. 点击代码块右上角“复制”可复制原始代码内容；点击“格式化”会先确认，再把格式化结果放入编辑模式供检查和保存。
13. 如果保存时提示文档已在外部更新，请先复制需要保留的草稿内容，再刷新阅读视图或重新打开阅读器，基于最新内容继续编辑。

导出 HTML

• 导出的 HTML 是无脚本离线阅读文件，包含当前渲染正文、大纲、阅读样式和代码高亮样式。
• 导出文件不会包含 Webview 脚本、编辑 textarea、保存按钮、源码定位按钮或 VS Code API 调用。
• Markdown 原始 HTML 仍按阅读器安全策略转义；危险链接和越界图片路径继续被阻断。
• 本地图片会沿用当前安全资源路径策略；导出后如果移动 HTML 文件，建议同时保留原图片文件位置或后续使用更完整的资源归档方案。

阅读外观配置

可在 VS Code / Trae 设置中搜索 Markdown Reader 或直接配置以下选项：

• mdReader.appearance.fontSize：正文基础字体大小，默认 16，范围 12 到 24，单位为 px。
• mdReader.appearance.lineWidth：正文最大行宽，默认 920，范围 640 到 1200，单位为 px。
• mdReader.appearance.lineHeight：正文行距，默认 1.75，范围 1.3 到 2.2。
• mdReader.appearance.defaultTheme：默认主题，支持 system、light、dark；system 表示跟随 VS Code 当前颜色主题。

外观设置会在新打开或刷新阅读视图时生效。若你已在阅读视图内点击“切换主题”，该手动主题偏好会优先于 defaultTheme。

当前框架与路线图

框架现状

• 扩展入口：src/extension.ts 注册 mdReader.openReader 与 mdReader.formatMarkdown 命令、.md 编辑器标题栏和右键菜单入口，按文档 URI 维护阅读面板，监听保存事件以 400ms debounce 刷新，并监听源码选区变化同步阅读位置。
• Markdown 渲染器：src/renderer/markdown.ts 基于 markdown-it 与 highlight.js 生成正文 HTML、大纲、稳定标题锚点、块级 data-line 行号映射、只读任务列表 checkbox、目录 Markdown、阅读统计、Mermaid 预览占位、数学公式和代码复制按钮，同时保留源码定位按钮。
• Webview HTML：src/webview/readerHtml.ts 负责注入 CSP、nonce、样式和脚本资源，生成阅读工具栏、搜索栏、统计栏、工作区索引、编辑区、导出入口、大纲导航和无脚本离线 HTML。
• Webview 脚本：src/webview/reader.js 负责大纲显隐与状态恢复、主题切换、正文搜索、复制反馈、目录复制、工作区索引过滤、显式格式化、编辑草稿保护、保存 / 导出消息、源码跳转、源码到阅读同步和滚动高亮。
• 安全工具：src/security.ts 限制安全链接协议、本地图片路径和目录边界，src/utils/html.ts 负责 HTML / 属性转义；Webview CSP 默认禁止脚本、样式和图片以外的非授权资源。
• 类型定义：src/types.ts 定义主题偏好、外观配置、渲染结果、保存结果、导出结果和 Webview 消息结构，是扩展端与 Webview 交互的共享契约。
• 测试与打包：test/markdown.test.ts 覆盖渲染、安全过滤、配置贡献、Webview 输出、离线 HTML、右键菜单和包内容；package.json 提供 compile、test、vscode:prepublish、package 和 watch 脚本，.vscodeignore 控制 VSIX 产物内容。

已实现能力校准

• 基础阅读：已支持从命令、编辑器标题栏和 .md 右键菜单打开独立 Webview 阅读视图。
• 渲染增强：已支持 markdown-it 常用语法、嵌套列表、表格、引用、任务列表只读 checkbox、代码块高亮、Mermaid 预览占位、数学公式、链接和本地图片安全处理。
• 阅读交互：已支持大纲导航、默认隐藏 / 手动显示大纲、侧边栏状态恢复、浅色 / 深色主题切换、阅读视图搜索、代码复制、目录复制、阅读统计、工作区文档索引和源码定位按钮。
• 编辑闭环：已支持阅读视图内整篇 Markdown 原文编辑、保存回源文件、取消编辑、外部更新冲突保护和未保存草稿恢复。
• 同步与导出：已支持源码光标到阅读块的防抖同步、阅读块到源码定位，以及导出无脚本离线 HTML。
• 外观与发布：已支持字体大小、正文行宽、行距、默认主题配置、显式格式化命令，并具备编译、测试、发布前检查和 VSIX 打包链路。

待开发功能分析

P0

P1

P2

待优化项分析

P0

P1

P2

推荐实施顺序

1. 当前 ROADMAP_TASKS.md 中列出的 P0 / P1 / P2 事项已完成并纳入测试与文档。
2. 后续新增能力应继续先写入 ROADMAP_TASKS.md，实现后同步 README、CHANGELOG 和测试。
3. 若未来引入真正 Mermaid / KaTeX / Prettier 依赖，需要单独评估 CSP、包体积、离线能力和失败回退。

全网功能调研与可加入功能建议

调研来源与高价值能力

调研功能状态校准

调研结论

1. 已实现的搜索、同步、草稿保护、任务列表、外观配置、导出 HTML、Mermaid 预览、复制代码块、目录复制、阅读统计、格式化、数学公式和多文档索引不再列为待开发功能，仅作为回归验证和优化对象。
2. 后续若需要更完整的 Mermaid / 数学公式 / Markdown 格式化能力，应作为依赖评估型任务单独设计。
3. PlantUML / 外部服务、协同编辑和完整 IDE 继续保持排除。

隐私与安全

• Markdown 内容只在本地 VS Code 扩展进程与 Webview 中处理。
• 插件不上传文档、不要求账号登录、不启用遥测。
• Webview 的本地资源访问范围限制在当前 Markdown 文件所在目录。
• 外部网络图片会被阻止显示，避免阅读时主动加载远程资源。
• javascript:、协议相对地址等危险链接会被拦截，本地图片路径不能越过当前 Markdown 文件所在目录。

开发

安装依赖：

npm install

编译：

npm run compile

测试：

npm test

发布前检查：

npm run vscode:prepublish

VSIX 打包：

npm run package

本地安装 VSIX：

code --install-extension vscode-md-reader-0.0.2.vsix

在 Trae CN IDE 中安装 VSIX：

1. 执行 npm run package 生成 vscode-md-reader-0.0.2.vsix。
2. 在 Trae CN IDE 打开扩展视图。
3. 选择从 VSIX 安装，并选中生成的 VSIX 文件。
4. 重新加载窗口后打开 .md 文件，执行 Markdown Reader: 打开 Markdown 阅读器，或在编辑器中右键选择“打开 Markdown 阅读器”。

在 VS Code 中调试：

1. 打开本项目目录。
2. 确保已执行 npm install。
3. 在“运行和调试”中选择 Run Extension 配置。
4. 启动 Extension Host 后打开任意 .md 文件，执行命令 Markdown Reader: 打开 Markdown 阅读器，或在编辑器中右键选择“打开 Markdown 阅读器”。

调试依赖以下 VS Code 配置文件：

• .vscode/launch.json：使用 Extension Host 启动插件，并在启动前执行 npm: compile。
• .vscode/tasks.json：提供 npm: compile 与 npm: watch 两个任务，分别用于一次性编译与监听编译。

发布说明

• npm run vscode:prepublish 会先编译插件，再执行测试，适合作为发布前检查。
• npm run package 使用 VS Code 官方 VSIX 打包工具生成安装包。
• .vscodeignore 会排除源码、测试、.trae 规格文档、.vscode 调试配置、sourcemap、临时文件和历史 VSIX。
• 发布包保留运行所需的 out、Webview 静态资源、package.json、README.md、LICENSE 和 CHANGELOG.md。

变更日志

0.0.2

• 使用 markdown-it 替代手写解析器，提升复杂 Markdown 语法兼容性。
• 引入 highlight.js 代码高亮，并随 VSIX 打包 Webview 样式与脚本资源。
• 保存刷新增加 400ms debounce，Webview CSS / JS 拆分为独立资源，CSP nonce 改为加密安全随机值。
• 修复大纲点击跳转，增加侧边栏隐藏 / 显示能力，并优化打印 / 导出 PDF 点击反馈。
• 新增阅读视图 Markdown 原文编辑模式，支持保存、取消、保存状态提示和外部变更冲突保护。
• 新增阅读视图内搜索，支持结果高亮、计数、上一个 / 下一个导航和编辑模式清理。
• 补充复杂 Markdown 渲染、安全过滤、右键菜单与包内容验证链路。

0.0.1

• 提供本地 Markdown 阅读 Webview、文档大纲、主题切换、源码定位和打印导出入口。

.vscode/launch.json 内容：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run Extension",
      "type": "extensionHost",
      "request": "launch",
      "args": [
        "--extensionDevelopmentPath=${workspaceFolder}"
      ],
      "outFiles": [
        "${workspaceFolder}/out/**/*.js"
      ],
      "preLaunchTask": "npm: compile"
    }
  ]
}

.vscode/tasks.json 内容：

{
  "version": "2.0.0",
  "tasks": [
    {
      "type": "npm",
      "script": "compile",
      "group": "build",
      "problemMatcher": "$tsc",
      "label": "npm: compile"
    },
    {
      "type": "npm",
      "script": "watch",
      "group": "build",
      "isBackground": true,
      "problemMatcher": "$tsc-watch",
      "label": "npm: watch"
    }
  ]
}