Textaro

一个专注、轻量的本地 Markdown 工作空间编辑器

使用 Electron、Vue 3、TypeScript 与 Milkdown 构建。

---

Textaro 将 Markdown 文件保留在你的本地目录中，并提供工作空间管理、所见即所得编辑、全文搜索以及 GitHub 同步能力。它不要求自有文件格式，也不会把内容锁定在应用内部。

Note

Textaro 当前处于早期开发阶段（v0.0.1），界面、配置格式和功能仍可能调整。

功能特性

• 本地优先：直接打开本地目录，Markdown 文件始终由你掌控。
• 所见即所得编辑：基于 Milkdown Crepe，支持标题、列表、任务列表、引用、代码块、表格、图片和公式等常用内容。
• 工作空间管理：添加本地目录，或从 GitHub 克隆远程仓库。
• 文件树操作：创建和删除 Markdown 文件及目录，仅展示 .md / .markdown 文件和包含它们的目录。
• 多标签编辑：同时打开多个文档，并在关闭未保存内容前进行确认。
• 全文搜索：搜索文件名和 Markdown 内容，点击结果即可定位到对应文本。
• GitHub 同步：将工作空间快照同步到仓库默认分支；未绑定远程仓库时可自动创建私有仓库。
• 自动同步：可按秒设置同步间隔，设为 0 即关闭。
• 主题系统：支持浅色、深色、跟随系统，以及多套编辑器配色。
• 原生桌面体验：支持系统窗口边框与自定义标题栏。

技术栈

领域	技术
桌面运行时	Electron 33
前端框架	Vue 3
开发语言	TypeScript
构建工具	electron-vite / Vite
Markdown 编辑器	Milkdown Crepe
Git 能力	isomorphic-git
测试	Vitest
打包	electron-builder

快速开始

环境要求

• Node.js
• pnpm
• Git（用于克隆本仓库）

本地开发

git clone git@github.com:van23qf/Textaro.git
cd Textaro
pnpm install
pnpm run dev

开发模式支持 HMR，并会自动打开 Electron DevTools。

常用命令

# 启动开发环境
pnpm run dev

# 类型检查
pnpm run typecheck

# 运行测试
pnpm run test

# 构建应用
pnpm run build

# 预览构建产物
pnpm run preview

打包桌面应用

pnpm run build:win
pnpm run build:mac
pnpm run build:linux

安装包默认输出到 release/<version>/：

• Windows：NSIS 安装包、ZIP
• macOS：DMG、ZIP
• Linux：AppImage、DEB

跨平台打包可能需要对应操作系统的签名工具或额外环境。更稳妥的方式是在目标平台上执行打包命令。

使用指南

添加工作空间

打开“创建工作空间”对话框后，可以：

1. 选择“本地目录”，直接添加已有目录。
2. 选择“远程仓库”，输入 github.com 的 HTTPS 或 SSH 仓库地址，并选择本地存储位置。

目录树会跳过隐藏项和符号链接，仅展示 Markdown 文件及其所在目录。

编辑与保存

选择文件后会在新标签中打开。编辑内容出现未保存更改时，标签会显示状态标记。

• Windows / Linux：Ctrl + S
• macOS：⌘ + S

在文件树空白处、文件或目录上点击右键，可以创建或删除内容。

配置 GitHub 同步

1. 在“设置 → 同步”中填写 GitHub Token。
2. 添加一个带 GitHub 远程地址的本地仓库，或直接从 GitHub 克隆工作空间。
3. 点击工作空间顶部的同步按钮；也可以配置自动同步间隔。

首次同步一个尚未绑定远程仓库的工作空间时，Textaro 会尝试在 GitHub 创建同名的私有仓库。Token 需要具备相应仓库的读取、写入权限；需要自动创建仓库时，还应具备创建仓库的权限。

Warning

GitHub 同步以本地工作空间为准生成完整快照，并更新远程仓库的默认分支。本地已删除的文件会在下一次同步后从远端快照中移除。请勿把它当作双向合并工具；同步前建议确认远端没有其他人刚提交的更改。

同步时：

• 遵循工作空间中的 .gitignore。
• 不上传 .git 目录、符号链接或非普通文件。
• 单个文件不能超过 GitHub 的 100 MB 限制。
• 如果远端分支在同步期间发生变化，操作会停止并提示重试，不会强制覆盖分支。

数据与安全

• 渲染层启用了 contextIsolation 和沙箱，不直接访问 Node.js。
• 文件能力通过 workspaceId + relativePath 的窄化 IPC 暴露，并校验目标路径位于工作空间内。
• 应用配置保存在用户主目录的 textaro.json。
• GitHub Token 也保存在该本地配置文件中；请保护好系统账户与配置文件，避免分享或提交该文件。
• 从设置中移除工作空间只会删除 Textaro 中的记录，不会删除本地目录。
• 在文件树中删除文件或目录会直接修改磁盘内容，且不可恢复。

项目结构

Textaro/
├─ src/
│  ├─ main/                 # Electron 主进程、文件系统与 GitHub API
│  ├─ preload/              # contextBridge 与渲染层 API 类型
│  ├─ renderer/             # Vue 3 界面、编辑器与主题
│  └─ shared/               # 主进程与渲染层共享类型
├─ tests/                   # Vitest 测试
├─ design/                  # 设计规范、决策记录与参考原型
├─ electron.vite.config.ts  # Electron Vite 配置
└─ electron-builder.yml     # 桌面应用打包配置

主进程、预加载脚本与渲染层保持职责分离：

Vue Renderer
     │
     │ window.textaro
     ▼
Preload / contextBridge
     │
     │ narrow IPC
     ▼
Electron Main ─── Local Files / GitHub API

参与开发

欢迎通过 Issue 描述问题或建议，也欢迎提交 Pull Request。

提交代码前请确保以下命令通过：

pnpm run typecheck
pnpm run test
pnpm run build

开发时请注意：

• 使用 pnpm 管理依赖。
• 不要直接编辑 out/ 构建产物。
• 渲染层视觉样式应使用 src/renderer/src/styles/tokens.css 中的设计变量。
• 新增主进程能力时应继续使用窄化 IPC 与 contextBridge，不要开启 nodeIntegration。
• preload 必须保持 CommonJS 输出，以兼容 Electron 沙箱模式。

许可证

本项目采用 GNU General Public License v3.0（GPL-3.0-only）开源。