# markdown-editor-electron

**Repository Path**: acomma/markdown-editor-electron

## Basic Information

- **Project Name**: markdown-editor-electron
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-27
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Markdown Editor（Electron）

分屏式 Markdown 桌面编辑器：左侧 CodeMirror 源码编辑，右侧 markdown-it 实时渲染预览。

- 主进程 / 预加载 / 渲染进程三层分离（`contextIsolation: true`、`nodeIntegration: false`）
- 工作区文件树 + 全文搜索替换 + 图片管理
- 实时语法检查、表格可视化编辑、链接与标题自动补全、代码片段、自定义快捷键
- 打字机模式、同一文档双窗格对照、Git 版本历史（只读）
- 导出 HTML / PDF / Word(.docx) / EPUB
- 可扩展主题：内置 4 套 + 在线主题市场安装

## 功能总览

按四期路线图组织，均已实现。

**第一期 基础设施**

| 功能 | 说明 |
|---|---|
| 设置系统 | 统一设置面板，localStorage 持久化 |
| 多主题 | 浅色 / 深色 / Solarized 浅色 / Solarized 深色 |
| 命令面板 | `Ctrl+Shift+P` 模糊搜索并执行命令 |
| 专注模式 | 隐藏侧栏与工具栏，只留编辑区 |
| 字数统计 | 状态栏字数 / 字符 / 行数 / 阅读时间、选区统计 |
| Frontmatter | YAML 解析、结构面板展示、预览中剥离且行号对齐 |

**第二期 编辑能力进阶**

| 功能 | 说明 |
|---|---|
| 标签页拖拽排序 | 拖动标签调整顺序，顺序随会话恢复 |
| 代码片段 | 表格 / 代码块 / 引用 / 任务列表 / details / 脚注 / KaTeX / mermaid |
| Markdown 语法检查 | 标题层级跳跃、缺空行、尾随空格（>2）等实时提示 |
| 表格可视化编辑 | 悬浮工具条增删行列与对齐，`Alt+方向键` 单元格导航 |
| 链接与标题自动补全 | `[文字`、`](路径`、`](路径#锚点` 三种上下文补全 |
| 自定义快捷键 | 可视化录制、冲突检测、重置与解除 |

**第三期 高级功能**

| 功能 | 说明 |
|---|---|
| 打字机模式 | 光标行始终居中显示 |
| 文档分屏查看 | 同一文档双窗格，第二窗格为只读镜像、滚动独立 |
| 图片管理面板 | 工作区图片缩略浏览、插入文档、重命名、移动、删除 |
| Git 集成 | 单文件版本历史与 vs 当前内容的着色 diff（只读） |
| 导出格式扩展 | Word(.docx) / EPUB（mermaid 光栅化、图片内嵌） |

**第四期 工程化与发布**

| 项 | 说明 |
|---|---|
| 自动化测试 | Vitest 纯逻辑单测 + CDP 冒烟脚本 |
| 跨平台打包 | Windows NSIS、macOS dmg/zip、Linux AppImage/tar.gz 配置与应用图标 |
| 项目文档 | 本 README、CHANGELOG、LICENSE |
| 主题市场 | 在线索引浏览、一键安装/卸载主题 |

## 技术栈

Electron 44 · React 18 · TypeScript 5.9 · electron-vite 5（Vite 7）· CodeMirror 6 · markdown-it 15 · highlight.js · KaTeX · mermaid · Zustand 5 · electron-builder 26

## 目录结构

```
src/
  main/          主进程：窗口、菜单、文件 / 工作区 / 导出 / 会话 / Git / 主题 handler
  preload/       contextBridge 暴露的 window.api（invoke 型 + onXxx 订阅）
  shared/        main 与 renderer 共用类型与纯逻辑（keybindings、theme-package、markdown-anchor）
  renderer/src/
    components/  界面组件（编辑器面板、预览、工作区、各类对话框）
    editor/      CodeMirror 扩展（格式、表格、lint、补全、打字机、镜像同步）
    markdown/    渲染管线（markdown-it 规则、frontmatter、目录、mermaid）
    store/       Zustand：document / ui / settings
    themes/      主题表、已安装主题 CSS 注入、加载器
    lib/         纯工具（统计、路径、模糊匹配、CSS 作用域）
tests/           Vitest 单测
.smoke/          CDP 运行时冒烟脚本
themes/          主题市场索引与示例主题包
tools/           图标生成脚本
build/           打包资源（应用图标）
```

## 开发

要求 Node.js ≥ 20（推荐 24，与 Electron 44 内置版本一致）。

```bash
npm install
npm run dev                 # 启动开发窗口（HMR）

npm run typecheck           # main / renderer / tests 三个项目全量类型检查
npm run test                # Vitest 纯逻辑单测
npm run test:watch          # 单测 watch 模式

# 冒烟测试（Windows，需要真实窗口与桌面焦点）
npm run dev -- --remote-debugging-port=9222   # 另开一个终端常驻
npm run smoke                                 # 50 项 CDP 断言
```

## 打包

```bash
npm run build:win     # Windows：NSIS 安装包（可在 Windows 上直接构建）
npm run build:mac     # macOS：dmg + zip（x64 / arm64，需在 macOS 上构建）
npm run build:linux   # Linux：AppImage + tar.gz（需在 Linux 上构建）
```

- 产物输出到 `release/`，产物与 `out/` 均已加入 `.gitignore`
- 应用图标由 `node tools/make-icon.mjs`（程序化绘制 1024 PNG）与 `node tools/make-icons.mjs`（派生 ico / icns / png）生成
- **macOS 未做签名与公证**：首次打开需右键「打开」，或在「系统设置 → 隐私与安全性」中放行
- **未提供 deb**：deb 需要 `package.json` 的 `author.email`，补全后可自行在 `electron-builder.yml` 的 linux target 中加入 `deb`

## 快捷键

设置 → 快捷键中可自定义（录制需含 Ctrl 的组合，`Backspace` 解除、`Esc` 取消；冲突会拒绝并提示占用方）。

**默认菜单命令**

| 组合 | 命令 |
|---|---|
| `Ctrl+N` | 新建 |
| `Ctrl+O` | 打开… |
| `Ctrl+Alt+O` | 打开文件夹… |
| `Ctrl+S` | 保存 |
| `Ctrl+Shift+S` | 另存为… |
| `Ctrl+1` / `Ctrl+2` / `Ctrl+3` | 仅编辑器 / 分屏 / 仅预览 |
| `Ctrl+Shift+O` | 显示/隐藏大纲 |
| `Ctrl+Shift+F` | 显示/隐藏工作区 |
| `Ctrl+Shift+D` | 切换主题 |
| `Ctrl+Alt+F` | 专注模式 |
| `Ctrl+Shift+P` | 命令面板 |
| `Ctrl+,` | 打开设置 |

**编辑器内置键**（焦点在编辑器内时生效，优先于自定义绑定）

| 组合 | 行为 |
|---|---|
| `Ctrl+B` / `Ctrl+I` / `Ctrl+Shift+X` | 加粗 / 斜体 / 删除线 |
| `Ctrl+E` / `Ctrl+K` | 行内代码 / 链接 |
| `Tab` / `Shift+Tab` | 缩进 / 反缩进 |
| `Enter` | 列表续接（`-`、`1.`、`- [ ]`） |
| `Alt+↑` / `Alt+↓` / `Alt+←` / `Alt+→` | 表格单元格导航 |

无默认快捷键（可自行绑定）：文档分屏对比、版本历史、各导出命令、代码片段与表格操作命令。

## 主题与主题市场

内置主题：浅色、深色、Solarized 浅色、Solarized 深色（设置 → 主题中切换，或 `Ctrl+Shift+D` 循环）。

主题市场（设置 → 主题 → 浏览主题市场）从远端索引拉取主题列表，一键安装后即可切换、随时卸载。索引地址与示例主题包位于仓库 `themes/` 目录：

```json
[
  { "id": "sunset-paper", "name": "日落纸笺", "dark": false, "version": "1.0.0",
    "description": "…", "url": "https://…/themes/sunset-paper.json" }
]
```

**主题包格式**

```json
{
  "id": "sunset-paper",
  "name": "日落纸笺",
  "dark": false,
  "version": "1.0.0",
  "description": "可选",
  "variables": { "--bg": "#fff8f2", "--accent": "#c2410c" }
}
```

校验规则（主进程 `src/shared/theme-package.ts`）：

- `id`：`^[a-z0-9][a-z0-9-]{1,31}$`，不得与内置 id 冲突，且必须与索引条目一致
- `variables`：仅允许以下 24 个变量；字号/字体 3 个变量（`--editor-font-size`、`--editor-font-family`、`--preview-font-size`）由设置项运行时写入，禁止主题覆盖
- 必备变量（13 个色板）：`--bg` `--bg-secondary` `--bg-hover` `--bg-active` `--border` `--text` `--text-secondary` `--text-muted` `--accent` `--green` `--green-hover` `--yellow` `--danger`
- 可选语法高亮变量：`--dialog-shadow`、`--syntax-keyword`、`--syntax-operator`、`--syntax-variable-special`、`--syntax-type`、`--syntax-atom`、`--syntax-number`、`--syntax-definition`、`--syntax-string`、`--syntax-comment`、`--syntax-meta`
- 变量值 ≤ 64 字符，仅允许 `#(),.%`、字母数字、空白与 `-`，并拒绝 `url(` / `expression(` / `@import`
- 安装位置：`<userData>/themes/<id>.json`（Windows 为 `%APPDATA%\markdown-editor-electron\themes\`）

## 安全说明

- 渲染进程不发起任何外部网络请求；主题索引与下载全部在主进程用 `net.fetch` 完成
- 主题 CSS 经变量名/值白名单校验后，以单个 `<style>` 标签注入
- `contextIsolation: true`、`nodeIntegration: false`，`window.open` 一律交给系统浏览器
- **尚未设置 CSP**：加严会牵动 `mdimg://` 本地图片协议与 KaTeX CDN 字体，留待后续迭代（已知项）

## 已知限制

- 文档分屏的第二窗格为只读镜像（可编辑双窗格未实现）
- Git 集成为只读：可查看历史与 diff，不提供暂存/提交/推送
- 图片重命名/移动不会回填已打开文档中的旧引用（操作后会有提示）
- 表格编辑不支持引用块 / 列表内的表格；多光标只取主选区
- 导出 DOCX/EPUB 时 KaTeX 公式依赖 CDN 字体，离线打开会缺字体
- 冒烟测试依赖 Windows 桌面焦点（通过 Win32 API 激活窗口），非 Windows 需自行改造

## 许可证

[MIT](LICENSE) © 2026 acomma