# ReadMarkProject

**Repository Path**: chinaqi/read-mark-project

## Basic Information

- **Project Name**: ReadMarkProject
- **Description**: vscode ReadMark 插件
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-31
- **Last Updated**: 2026-08-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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

| 待开发功能 | 用户价值 | 涉及模块 | 主要风险 | 验收标准 |
| --- | --- | --- | --- | --- |
| Mermaid 图表预览 | 已完成：技术文档中的流程图、时序图和状态图可在阅读视图直接查看，减少切换到外部工具 | `src/renderer/markdown.ts`、`src/webview/reader.js`、`src/webview/styles.css`、`test/markdown.test.ts` | 当前为本地轻量预览占位和错误回退，未引入远程依赖 | `mermaid` 代码块渲染为图表预览区域；语法错误显示原始代码和错误提示；离线、安全和无遥测边界保持不变；测试覆盖成功、失败和安全场景 |

#### P1

| 待开发功能 | 用户价值 | 涉及模块 | 主要风险 | 验收标准 |
| --- | --- | --- | --- | --- |
| 复制代码块 | 已完成：用户阅读技术文档时可一键复制代码，提升教程、命令和示例的使用效率 | `src/renderer/markdown.ts`、`src/webview/reader.js`、`src/webview/styles.css`、`test/markdown.test.ts` | 依赖 Webview 剪贴板权限，失败时需要清晰反馈 | 每个代码块显示复制入口；复制成功 / 失败有明确反馈；导出 HTML 不包含 Webview 专用复制脚本；代码内容保持原文 |
| 文档目录页生成 | 已完成：用户可基于当前标题结构生成 Markdown 目录片段，用于补充到源码文档 | `src/renderer/markdown.ts`、`src/webview/reader.js`、`src/types.ts`、`test/markdown.test.ts` | 重复标题、中文标题和特殊字符锚点必须与现有大纲规则一致 | 可生成并复制目录 Markdown；目录链接能跳转到当前阅读锚点；重复标题生成稳定；不直接覆盖源文件 |
| 阅读统计 | 已完成：用户可快速了解字数、标题数、代码块数量和预计阅读时间，辅助评估长文档 | `src/renderer/markdown.ts`、`src/types.ts`、`src/webview/readerHtml.ts`、`test/markdown.test.ts` | 中文 / 英文混合统计口径需保持一致，避免统计 HTML 标签或代码高亮标记 | 阅读视图展示统计信息；保存刷新后同步更新；中文、英文、代码块和空文档统计稳定 |

#### P2

| 待开发功能 | 用户价值 | 涉及模块 | 主要风险 | 验收标准 |
| --- | --- | --- | --- | --- |
| 工作区多文档阅读索引 | 已完成：用户可从阅读器快速切换同一工作区内的 Markdown 文件，适合大型文档库 | `src/extension.ts`、`src/webview/readerHtml.ts`、`src/webview/reader.js`、`src/types.ts`、`package.json` | 大工作区扫描需要限制数量并排除构建目录 | 索引面板可列出工作区 Markdown；支持搜索过滤和点击打开 / 切换；大工作区限制为最多 200 个结果 |
| 显式 Markdown 格式化入口 | 已完成：用户可按需统一标题空格、行尾空格和连续空行，但不会在保存时被自动改写 | `package.json`、`src/extension.ts`、`src/webview/reader.js`、`test/markdown.test.ts` | 轻量格式化不会覆盖完整 Prettier 表格对齐能力 | 仅通过显式命令触发；格式化前展示确认；可撤销；代码块和任务列表内容保持稳定 |
| 数学公式渲染 | 已完成：学术、工程和算法文档可直接阅读行内 / 块级公式 | `src/renderer/markdown.ts`、`src/webview/styles.css`、`test/markdown.test.ts` | 当前为轻量本地渲染，不引入 KaTeX / MathJax 依赖 | 行内和块级公式可渲染；渲染失败不影响正文；VSIX 体积增长可接受；普通货币符号不误判 |

### 待优化项分析

#### P0

| 待优化项 | 问题原因 | 收益 | 涉及模块 | 主要风险 | 验证方式 |
| --- | --- | --- | --- | --- | --- |
| 路线图与已实现状态持续校准 | 已完成：路线图和任务清单已更新为当前实现状态 | 后续任务选择更准确，减少重复实现和文档漂移 | `README.md`、`CHANGELOG.md`、`ROADMAP_TASKS.md`、`.trae/specs/*/tasks.md` | 维护成本增加，需要每次功能完成后同步更新状态 | README 待开发列表不包含未校准状态；CHANGELOG 明确记录状态校准；任务清单依赖关系清晰 |
| 编辑保存冲突提示优化 | 已完成：外部更新冲突提示已包含拒绝覆盖、复制草稿、刷新和重新编辑建议 | 降低误操作和草稿丢失风险，让用户知道恢复顺序 | `src/extension.ts`、`src/webview/reader.js`、`test/markdown.test.ts` | 提示较长，需要保持清晰 | 模拟打开后外部修改再保存，确认拒绝覆盖、提示包含恢复建议、草稿仍保留且可复制 |
| 本地资源安全边界回归补强 | 已完成：安全回归测试覆盖本地图片、上级目录、协议相对地址、危险协议和特殊字符路径 | 保持本地、安全、轻量定位，避免路径穿越和远程资源泄露 | `src/security.ts`、`src/renderer/markdown.ts`、`test/markdown.test.ts` | 策略过严可能误伤合法相对路径或特殊字符文件名 | 执行 `npm test` 验证本地图片、上级目录、协议相对地址、`javascript:`、`data:`、特殊字符路径用例 |

#### P1

| 待优化项 | 问题原因 | 收益 | 涉及模块 | 主要风险 | 验证方式 |
| --- | --- | --- | --- | --- | --- |
| 大文档渲染性能优化 | 已完成：保留保存刷新 debounce，并增加阅读统计与工作区索引数量限制，避免新增能力放大卡顿 | 提升大文件打开、保存刷新和搜索定位体验 | `src/extension.ts`、`src/renderer/markdown.ts`、`src/webview/reader.js` | 当前仍非虚拟列表，极端超大文档仍可能受整页渲染影响 | `npm test` 覆盖渲染链路；工作区扫描最多 200 个 Markdown；确认 400ms debounce 与同步行为稳定 |
| Webview 交互可访问性优化 | 已完成：新增按钮、搜索、统计、索引和状态反馈均提供基础 aria / role / status | 提升键盘用户和辅助技术用户的阅读 / 编辑体验 | `src/webview/readerHtml.ts`、`src/webview/reader.js`、`src/webview/styles.css`、`test/markdown.test.ts` | 复杂焦点恢复仍需真实 VS Code 手动回归 | 用键盘完成打开搜索、切换结果、进入编辑、取消、导出、复制目录和文档索引；检查 aria 状态和提示区域 |
| Webview 资源体积优化 | 已完成：Mermaid 与公式采用轻量本地实现，不新增 npm 运行依赖；导出 HTML 自动移除 Webview 专用复制按钮 | 减少 VSIX 体积并缩短 Webview 首次加载时间 | `src/webview/styles.css`、`src/webview/reader.js`、`src/webview/highlight.css`、`.vscodeignore`、`package.json` | 单文件 CSS / JS 继续增长，后续大重构时可拆分 | 执行 `npm run package` 后检查 VSIX 内容和体积，打开阅读视图确认样式、脚本、搜索、编辑和代码高亮正常 |

#### P2

| 待优化项 | 问题原因 | 收益 | 涉及模块 | 主要风险 | 验证方式 |
| --- | --- | --- | --- | --- | --- |
| Webview 脚本可维护性重构 | 已完成：在单文件内按状态、复制、索引、格式化、同步和消息处理分区，避免本轮大拆文件带来回归 | 降低新增功能成本，让状态初始化、事件绑定和 DOM 更新更容易测试 | `src/webview/reader.js`、`src/webview/readerHtml.ts`、`src/types.ts`、`test/markdown.test.ts` | 尚未拆成多个文件，后续大规模功能仍建议模块化 | 执行 `npm run compile` 和 `npm test`，并手动回归大纲、搜索、编辑、导出和源码同步 |
| Markdown 兼容性样例扩展 | 已完成：新增 Mermaid、数学公式、代码复制、安全链接、本地资源、任务列表和 Webview 输出测试 | 降低真实文档解析差异，增强用户迁移已有 Markdown 的信心 | `src/renderer/markdown.ts`、`src/security.ts`、`test/markdown.test.ts` | 增强兼容性时不能放宽危险 HTML、危险协议和本地资源边界 | `npm test` 覆盖嵌套列表、复杂链接、危险链接、任务列表、公式、Mermaid 和本地资源边界 |
| 发布与文档流程模板化 | 已完成：README、CHANGELOG、ROADMAP_TASKS 和发布命令说明已同步，任务清单可直接勾选跟踪 | 形成轻量发布清单，减少文档与实际能力不一致 | `README.md`、`CHANGELOG.md`、`ROADMAP_TASKS.md`、`package.json` | 模板过细会增加维护负担，需要保持可执行而非形式化 | 发布前核对 README 功能、CHANGELOG 条目、任务清单、版本号、VSIX 名称和 `npm run vscode:prepublish` 结果 |

### 推荐实施顺序

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

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

### 调研来源与高价值能力

| 来源 | 高价值功能点 | 对 Markdown Reader 的适配判断 |
| --- | --- | --- |
| [Markdown Prettier](https://marketplace.visualstudio.com/items?itemName=lyhlg.markdown-prettier) | Markdown 格式化、列表缩进统一、表格排版、保存时自动整理 | 适合作为编辑辅助能力，但当前插件定位是本地阅读视图，应优先做“可选格式化入口”和“格式化前预览 / 确认”，避免保存时自动改写用户原文。 |
| [Markdown Preview Enhanced](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced) | Mermaid / PlantUML 等图表、导出 HTML / PDF、目录、数学公式、代码块增强、预览同步滚动 | 图表、导出、目录和同步定位与阅读器目标高度相关；公式和多渲染后端会增加依赖、CSP 与包体积风险，适合分阶段加入。 |
| [Super Markdown](https://marketplace.visualstudio.com/items?itemName=SivanLiu.super-markdown) | 阅读模式、结构化大纲、任务列表、图片与链接体验、面向写作的快捷操作 | 大纲、任务列表和资源体验与现有能力契合；写作快捷操作应保持轻量，不应把阅读器扩展成完整 Markdown IDE。 |
| [VS Code 官方 Markdown 能力](https://vscode.js.cn/docs/languages/markdown) | 内置预览、侧边预览、源码与预览联动、工作区安全、命令与菜单集成、Markdown 扩展点 | 应继续遵循 VS Code Webview 安全模型、命令入口和工作区信任约束；侧边预览与联动能力可作为本项目同步阅读体验的设计参考。 |
| [Markdown Preview Advance](https://marketplace.visualstudio.com/items?itemName=gwanjun.vscode-markdown-preview-advance) | 高级预览、实时刷新、图表 / 数学扩展、导出与样式定制 | 可借鉴“可配置外观 + 增强预览 + 导出”的组合，但需要坚持本地优先、默认安全和依赖克制。 |

### 调研功能状态校准

| 调研候选能力 | 当前状态 | 后续判断 |
| --- | --- | --- |
| 阅读视图内搜索 | 已实现 | 保留回归测试，后续重点优化大文档搜索性能和键盘可访问性。 |
| 源码与阅读位置双向同步 | 已实现 | 保留多文档隔离和编辑模式不干扰验证，后续优化重复标题、滚动抖动和长文档定位体验。 |
| 编辑草稿保护 | 已实现 | 保留取消、刷新、关闭和保存失败场景验证，后续优化外部更新冲突提示。 |
| 任务列表只读显示 | 已实现 | 继续保持只读边界，不在阅读状态点击写回源文件。 |
| 可配置阅读外观 | 已实现 | 后续可增加配置即时刷新和更完整的主题变量，但不作为新功能阻塞项。 |
| 导出 HTML | 已实现 | 后续优化本地图片归档、导出样式体积和失败提示。 |
| Mermaid 图表预览 | 已实现 | 当前采用轻量本地预览和失败回退，不引入远程依赖；若未来需要完整 SVG 渲染，再单独评估 Mermaid 依赖。 |
| 复制代码块 | 已实现 | 保留剪贴板失败反馈，并确保无脚本导出 HTML 不包含 Webview 专用复制按钮。 |
| 文档目录页生成 | 已实现 | 默认只复制目录片段，不直接覆盖源文件。 |
| 阅读统计 | 已实现 | 已展示中文、英文、标题、代码块和预计阅读时间统计。 |
| 工作区多文档阅读索引 | 已实现 | 扫描最多 200 个 Markdown，并支持阅读器内过滤与点击切换。 |
| 显式 Markdown 格式化入口 | 已实现 | 只能显式触发并提供确认，结果进入编辑流程或通过命令写入可撤销编辑。 |
| 数学公式渲染 | 已实现 | 当前采用轻量本地渲染，避免新增依赖体积和普通 `$` 文本误判风险。 |
| PlantUML / 外部图表服务 | 暂不建议 | 通常依赖 Java、本地服务或远程服务，默认不引入，除非未来确认完全本地、可选依赖和安全边界。 |
| 实时协同编辑 | 暂不建议 | 超出阅读器定位，需要账号、同步服务和冲突合并，不进入近期路线。 |
| 内置完整 Markdown IDE | 暂不建议 | 与 VS Code 编辑器已有能力重叠，容易功能膨胀，不作为当前插件目标。 |

### 调研结论

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

## 隐私与安全

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

## 开发

安装依赖：

```bash
npm install
```

编译：

```bash
npm run compile
```

测试：

```bash
npm test
```

发布前检查：

```bash
npm run vscode:prepublish
```

VSIX 打包：

```bash
npm run package
```

本地安装 VSIX：

```bash
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` 内容：

```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` 内容：

```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"
    }
  ]
}
```