|
| 1 | +# Markdown WYSIWYG Editor |
| 2 | + |
| 3 | +[English](README.md) | 简体中文 | [GitHub](https://github.com/git-xing/md-wysiwyg-editor) |
| 4 | + |
| 5 | +一款基于 [Milkdown](https://milkdown.dev/)（ProseMirror）的 VSCode 所见即所得 Markdown 编辑器扩展，以富文本方式直接编辑 `.md` / `.markdown` 文件，保存结果为标准 Markdown，与任何文本编辑器完全兼容。 |
| 6 | + |
| 7 | +*** |
| 8 | + |
| 9 | +## 功能特性 |
| 10 | + |
| 11 | +### 富文本编辑 |
| 12 | + |
| 13 | +- **标题**（H1–H6）、**粗体**、*斜体*、~~删除线~~、`行内代码`、引用块、分割线 |
| 14 | +- **有序列表 / 无序列表 / 任务列表**（点击复选框切换完成状态） |
| 15 | +- **链接**：悬停显示预览弹框，可直接修改链接文本和 URL；支持 `@/` workspace 路径、`#` 页内锚点跳转，以及 `file.md#27` 行号跳转 |
| 16 | +- **路径自动补全**：在 inline code 中输入 `@/`、`./`、`../` 等前缀，自动显示路径补全建议；分级目录浏览，带彩色文件类型图标 |
| 17 | + |
| 18 | +### 表格 |
| 19 | + |
| 20 | +- 完整的 GFM 表格支持 |
| 21 | +- **网格选择器**：悬停表格图标后拖拽选择行×列数再插入，无需手动输入 |
| 22 | +- 悬停行/列边框显示 **+ 插入线**，一键在任意位置插入行或列 |
| 23 | +- 行/列 **拖拽 handle**，点击选中整行/整列，拖拽即可重新排序 |
| 24 | +- 输入内容撑大表格后，插入线与 handle 实时跟随更新位置 |
| 25 | + |
| 26 | +### 代码块 |
| 27 | + |
| 28 | +- 语法高亮（支持 20+ 语言：Bash、C、C++、C#、CSS、Go、HTML、Java、JavaScript、JSON、Markdown、PHP、Python、Ruby、Rust、SQL、Swift、TypeScript、YAML） |
| 29 | +- 顶部语言选择器（含搜索筛选） |
| 30 | +- 一键复制代码按钮 |
| 31 | +- 拖拽底部 handle 调整代码块显示高度 |
| 32 | +- 全屏编辑器，含语法高亮；关闭时写回文档 |
| 33 | + |
| 34 | +### Mermaid 图表 |
| 35 | + |
| 36 | +- 流程图、时序图、甘特图、类图等内联渲染 |
| 37 | +- 源码与预览之间一键切换 |
| 38 | +- 支持缩放、平移（拖拽 / 触控板捏合），以及全屏 lightbox |
| 39 | + |
| 40 | +### 图片 |
| 41 | + |
| 42 | +- 支持从剪贴板**粘贴**、**拖放**文件，或通过**文件选择器**插入图片 |
| 43 | +- 本地存储（MD5 去重），或配置自定义服务器上传地址 |
| 44 | +- 点击图片选中，再次点击放大到 lightbox 预览 |
| 45 | +- 工具栏支持编辑 alt 文本、重命名文件、删除图片 |
| 46 | + |
| 47 | +### 自定义主题 |
| 48 | + |
| 49 | +- 支持通过 `markdownWysiwyg.customThemes` 配置项自定义主题颜色 |
| 50 | +- 在 `.vscode/settings.json` 中定义自定义主题名称和 VS Code 颜色 ID |
| 51 | +- 通过命令面板选择自定义主题："选择颜色主题" |
| 52 | +- 详见 [自定义主题配置](docs/custom-themes.md) |
| 53 | + |
| 54 | +### 目录（TOC） |
| 55 | + |
| 56 | +- 自动从文档标题生成目录面板 |
| 57 | +- 窗口宽度充足时自动展开；点击侧边 Tab 手动切换 |
| 58 | +- 点击条目平滑滚动至对应标题 |
| 59 | + |
| 60 | +### 工具栏 |
| 61 | + |
| 62 | +- 顶部固定工具栏：标题级别、加粗、斜体、删除线、有序/无序列表、任务列表、引用、代码块、表格 — 窗口收窄时自动折叠为溢出下拉菜单 |
| 63 | +- **选中文字浮动工具栏**：选中文字后弹出，支持快速格式化及发送到 Claude |
| 64 | +- **表格工具栏**：选中行/列后弹出，支持对齐、插入/删除行列 |
| 65 | + |
| 66 | +### 搜索与替换 |
| 67 | + |
| 68 | +- **`Cmd+F`**（macOS）/ **`Ctrl+F`**（Windows）：唤出 FindBar，在文档内搜索关键词 |
| 69 | +- **拖拽调整大小**：拖动底部 handle 可展开替换输入框 |
| 70 | +- **替换折叠**：点击箭头按钮切换替换模式 |
| 71 | +- **正则表达式**和**区分大小写**切换按钮 |
| 72 | +- 使用 CSS Custom Highlight API 实时高亮所有匹配项，颜色跟随 VS Code 主题 |
| 73 | +- `Enter` / `Shift+Enter` 上下导航，`Esc` 关闭 |
| 74 | + |
| 75 | +### Claude 集成 |
| 76 | + |
| 77 | +- **`Option+K`**（macOS）/ **`Alt+K`**（Windows）：将光标所在段落发送到 Claude 对话，自动附带精确文件行号 |
| 78 | +- 选中文字后点击工具栏「发送到 Claude」按钮，同样附带行号范围 |
| 79 | +- 自动识别 Claude 终端 / Claude VSCode 扩展 / VSCode 内置 Chat，三级降级兜底 |
| 80 | + |
| 81 | +### 自动保存 |
| 82 | + |
| 83 | +- 默认停止编辑 **1 秒**后自动写盘，无需手动 `Cmd+S` / `Ctrl+S` |
| 84 | +- 支持关闭自动保存，手动保存（标题栏显示 `●`） |
| 85 | +- 外部文件变更自动同步到编辑器（如 `git checkout`、其他编辑器修改） |
| 86 | + |
| 87 | +*** |
| 88 | + |
| 89 | +## 快速上手 |
| 90 | + |
| 91 | +安装扩展后，在 VSCode 中打开任意 `.md` / `.markdown` 文件，将自动以 WYSIWYG 模式打开。 |
| 92 | + |
| 93 | +| 操作 | 方式 | |
| 94 | +| ------------ | ----------------------------------- | |
| 95 | +| 切换到文本编辑器 | 点击标题栏 👁 图标，或右键文件 → 打开方式 | |
| 96 | +| 切换回 WYSIWYG | 点击标题栏 👁 图标 | |
| 97 | +| 插入表格（网格选择） | 悬停表格图标，拖拽选择行×列数 | |
| 98 | +| 插入行/列 | 鼠标悬浮表格行/列边框，点击 **+** | |
| 99 | +| 拖拽重排行/列 | 悬浮 **⠿** handle 后拖拽 | |
| 100 | +| 选中整行/整列 | 点击 **⠿** handle | |
| 101 | +| 路径自动补全 | 在 inline code 中输入 `@/`、`./` 或 `../` | |
| 102 | +| 发送段落到 Claude | `Option+K`（macOS）/ `Alt+K`（Windows） | |
| 103 | +| 文档内搜索 | `Cmd+F`（macOS）/ `Ctrl+F`（Windows） | |
| 104 | +| 手动保存 | `Cmd+S`（macOS）/ `Ctrl+S`（Windows） | |
| 105 | + |
| 106 | +*** |
| 107 | + |
| 108 | +## 设置 |
| 109 | + |
| 110 | +| 设置项 | 类型 | 默认值 | 说明 | |
| 111 | +| ------------------------------------ | ------- | ----------- | ---------------------------------------------------- | |
| 112 | +| `markdownWysiwyg.autoSave` | boolean | `true` | 编辑后自动写盘 | |
| 113 | +| `markdownWysiwyg.autoSaveDelay` | number | `1000` | 自动保存防抖延迟（毫秒） | |
| 114 | +| `markdownWysiwyg.defaultMode` | string | `"preview"` | 打开 `.md` 的默认模式：`preview`（WYSIWYG）或 `markdown`（文本编辑器） | |
| 115 | +| `markdownWysiwyg.codeBlockMaxHeight` | number | `600` | 代码块最大显示高度（像素） | |
| 116 | +| `markdownWysiwyg.editorMaxWidth` | number | `900` | 编辑器内容最大宽度（像素） | |
| 117 | +| `markdownWysiwyg.fontFamily` | string | `""` | 编辑器字体，留空继承 VSCode 编辑器字体，示例：`Georgia, serif` | |
| 118 | +| `markdownWysiwyg.imageStorage` | string | `"local"` | 图片存储模式：`local`（本地保存）或 `server`（上传至自定义 URL） | |
| 119 | +| `markdownWysiwyg.imageLocalPath` | string | `""` | 本地图片存储路径（相对于 workspace 根目录） | |
| 120 | +| `markdownWysiwyg.colorTheme` | string | `"auto"` | 颜色主题：`auto` 跟随 VSCode，或设置为特定主题 ID | |
| 121 | +| `markdownWysiwyg.tableWrap` | string | `"normal"` | 表格单元格文本换行：`normal`、`aggressive` 或 `none` | |
| 122 | +| `markdownWysiwyg.customThemes` | array | `[]` | 自定义颜色主题数组。详见 [自定义主题配置](docs/custom-themes.md) | |
| 123 | + |
| 124 | +*** |
| 125 | + |
| 126 | +## 环境要求 |
| 127 | + |
| 128 | +- VSCode **1.80.0** 及以上 |
| 129 | + |
| 130 | +*** |
| 131 | + |
| 132 | +## 已知限制 |
| 133 | + |
| 134 | +- 部分复杂 Markdown 扩展语法（如脚注、数学公式）尚未支持 |
| 135 | +- **链接弹窗撤销**（`Cmd+Z` / `Ctrl+Z`）：在链接 URL / 文字输入框内，撤销操作被 VS Code Electron 层拦截，暂无法使用 |
| 136 | +- **表格单元格行号**（发送到 Claude）：选中表格单元格时，上报的行号范围可能偏差，根因是 ProseMirror 节点索引与源码行号映射不对齐 |
| 137 | +- **全局搜索跳转**：点击 `.md` 文件的全局搜索结果时，若同时打开多个 `.md` 文件，WYSIWYG 编辑器可能无法精确跳转到匹配行 |
0 commit comments