1. 从"源码+预览"到即时渲染：Markdown编辑体验的进化节点
如果你写过一段时间 Markdown，大概率经历过这样的场景：左边是密密麻麻的#、*、[链接文字](地址)，右边是预览区，一边写一边眼睛来回扫。写了一上午，眼睛酸不说，最难受的是当你在源码里插入一张图片时，要等预览区刷新完，才发现图片路径写错了。这种"分裂式"写作体验，几乎成了 Markdown 用户的默认日常。
Markweave 这类 Markdown-first WYSIWYG 编辑器，做的正是把这套"源码+预览"的双栏模式彻底干掉。你打开它，看到的就是一篇排版完成的文档：一级标题就是大号字加粗，列表就是带圆点的列表，引用就是灰色块。但你的底层文件依然是标准 Markdown 语法，只是编辑器在输入过程中实时把语法渲染成了视觉样式，然后把光标藏进这些"已经好看"的文字里。
这背后涉及的远不止渲染层那点事。真正难啃的是光标模型和语法树的联动：当你在一个渲染好的标题行末敲回车，下一行该继承标题级别还是回到正文？当你在任务列表的[x]方括号上做删除操作，是按字符删还是把整个方括号状态切换掉？这些问题如果处理得粗糙，用户就会遇到"光标跳来跳去""排版突然错乱"之类的体验翻车。
所以标题里的"Markdown-first"值得划重点。它跟那种"支持 Markdown 导入"的在线文档不是一回事。Markdown-first 意味着 Markdown 源文本才是数据的唯一真实来源，WYSIWYG 只是它的展示层和编辑层。用户在界面上做的每一个加粗、每一处列表缩进，最终都被反向映射回 Markdown 文本里的对应语法片段。这跟 Notion 那种"块编辑器存 JSON 结构，Markdown 只是导入导出格式"的思路，在设计哲学上截然不同。
这个项目的目标用户其实很明确：一类是被双栏模式折磨得够呛的 Markdown 老手，想要 Typora 式的沉浸感，但又希望编辑器本身足够轻、可定制、数据完全在自己手里；另一类是刚入门 Markdown 的新用户，他们不想记一堆语法规则，只想像用 Word 一样排版，但在需要的时候又能摸到源文本。这两种需求看起来矛盾，Markweave 的 Markdown-first WYSIWYG 路线恰好把它们统一到了同一个文件格式上。
2. 深入 Markweave 的编辑器引擎：语法树、光标模型与双视图同步
2.1 源码文档与渲染视图之间的双向映射机制
要理解 Markweave 的内部逻辑，可以把它想象成一个"文档的两层皮"。底层是 Markdown 源文本，它是一个长字符串；上层是经过解析得到的语法树和渲染后的 DOM。编辑器引擎要维护这两层之间的一一对应关系。
工程上常见的做法是给每个语法节点加上位置信息。比如## 二级标题，解析器会标记出##是标记符，后面的文字是内容，两个部分加在一起形成 heading 节点，各有起始偏移量。当光标在渲染后的标题文字中间闪动时，编辑器需要把光标在 DOM 中的位置换算回源文本的偏移量，这样才能在用户输入时准确地把字符插入到源文本里。
Markweave 在这块的看点是它对"部分语法"的处理。正常的解析器遇到####这样的半截语法，要么报错，要么当纯文本。但在即时渲染模式里，用户正在敲第 3 个#，还没敲第 4 个，这时候编辑器既不能立刻把它渲染成标题，也不能当成纯文本显示出来让用户觉得"坏了"。Markweave 的做法是通过增量解析，在输入流处于不完整状态时，把当前节点标记为"未闭合"或"暂存"，等用户继续输入补齐语法后再完成最终渲染。
2.2 行内语法与光标定位的复杂场景
行内语法是 Markdown 解析里最容易出 bug 的地方，也是 Markdown-first WYSIWYG 和传统双栏编辑器拉开体验差距的关键。
以前写**加粗**，你看到的是一对星号加文字。在 Markweave 里，你敲下**时，星号会消失，光标后面的文字变成粗体。这时候问题来了：光标已经"掉进"了粗体文本内部，如果此时用户再敲一个*，Markweave 是把它当作加粗结束的标记，还是一段普通文字？这需要编辑器时刻记录当前光标处于哪个语法节点的内部，以及这个节点处于"已闭合"还是"未闭合"状态。
更刁钻的是嵌套场景。在一段文字里既有**粗体**，又有[链接](地址)，还有inline code，甚至链接文字本身又是粗体的。每一层节点叠加，光标的插入位置判断就需要遍历整棵语法树的分支。我在用 Markweave 写技术文章时，专门试过在一个列表项里写一段引用，引用里再嵌一个行内代码，代码里还有反引号和星号。它能正确渲染，但光标在反引号包围的区域内左右移动时，偶尔会出现一次性的跳动，这是节点边界处理时的回调滞后导致的，不频繁，但能感觉到。
2.3 即时渲染的性能策略
这里必须要提一下性能设计。WYSIWYG 编辑器最大的性能杀手，是"每次击键都全量重新解析整个文档"。Markweave 的应对思路是分层失效：
- 输入时，先判断光标所在的块级节点（标题、段落、列表项）是哪一块；
- 只对这一块的内容做块内重新解析和局部渲染；
- 如果本次输入涉及跨块操作（比如在列表中间按回车拆出一个新段落），则沿着语法树向上找到最近的公共父节点，从那里往下重新渲染。
这套逻辑说白了就是"能修补就不重建"。实际效果上，一个几万字的长篇技术文档，在输入时能明显感觉到按键延迟要比纯源码编辑器高一丁点，但整体处于可接受范围。如果拿浏览器自带的 MutationObserver 去观察 DOM 变化，你会发现数据量并不大，因为唯一变化的只会是光标所在的当前块。
3. 实操走一遍：从安装到产出一篇带标题、表格和公式的文章
3.1 环境准备与安装方式
Markweave 的安装比较简单，我的建议直接看项目 README 里的 release 页面。它提供三个渠道：桌面客户端、浏览器在线版和通过 npm 安装为本地 Web 应用。
桌面客户端适合每天要写长文的人，启动快、文件系统权限不受浏览器限制。我在本机的实践是直接用 npm 安装，然后作为 Web 应用跑在 localhost：8080 上。这种方式的好处是可以配合自己的代码工作区使用，写 Markdown 时顺手就把旁边的 JS 文件改了。
启动起来之后，Markweave 默认会打开一个欢迎文档。这个欢迎文档本身就是一篇 Markdown，里面介绍了快捷键、语法支持和配置项，你可以直接选中它按删除键清空，然后开始写自己的内容。第一次使用的人建议先在这个欢迎文档上练习，因为它把语法示例写得很全，省得你逐个翻文档。
3.2 基础编辑操作与常用快捷键
新用户最需要记住的是避免强迫自己继续敲 Markdown 符号。在 Markweave 里，加粗有三种方式：
- 直接按
Ctrl/Cmd + B，选中的文本立即变粗，源文件里自动写入**； - 手敲一个
*，再敲一个*，编辑器会补全配对的**，光标落在中间； - 选中一段文本，在浮出的迷你工具栏里点 B 按钮。
段落操作方面，最有价值的是按Ctrl/Cmd + 方向键调整列表项的层级关系。在普通 Markdown 编辑器里，缩进列表要通过先删除空格再重新输入的方式处理。在 Markweave 里，光标停在列表项开头，按一次Tab降级缩进，按Shift + Tab反缩进，渲染视图和源文档会同步更新对应层级的空格数。
Markweave 对表格的支持是我比较满意的部分。在源码模式下写一个表格，对齐线是个折磨人的事。在 WYSIWYG 模式下，你可以像用 Excel 一样直接按Tab在当前表格里跳到下一个单元格，输入完内容后回车会新建一行。编辑器自动替你计算每列的对齐和宽度。如果你经常需要把 Markdown 表格复制到 Word 或发布到公众号后台，这个能力非常省心，因为它生成的是标准 GFM 表格语法，不依赖扩展插件。
3.3 主题定制与导出配置
Markweave 的样式层基于 CSS 变量做的主题系统。你可以在设置面板直接改字体、字号、行高、代码块配色，这些设置会写入当前工作区的配置目录。如果你是一个"看主题不顺眼就想改"的人，建议直接编辑markweave.theme.css，里面每个变量都有注释，改起来没有门槛。
导出这一块，说实话 Markdown 编辑器的导出历来是重灾区。很多编辑器导出成 PDF 时，中文字体不是缺失就是错位。Markweave 在这方面走的路线是"委托浏览器打印能力"。你调用导出 PDF 时，它其实是调用 Chromium 的打印接口，所以导出的结果和你在编辑页面看到的几乎一致。我实测过导出包含中文和中英文混排的文档，字体方面只要你的操作系统装了中文字体，导出就没问题。另外它也支持直接导出为纯.md文件和带样式的 HTML 页面，后者特别适合快速做批量的文档站网页化。
4. 我踩过的坑：Markdown-first WYSIWYG 在实际写作中的边界
4.1 表格内的多行文本与<br>处理
第一个撞上的问题是，在 Markdown 表格的单元格里无法完成复杂的块级排版。Markweave 支持在 WYSIWYG 视图下编辑表格，但它依然受限于 Markdown 表格的语法能力。比如我在一个单元格里写了两行文字，想要一个换行，这时候 Markweave 会在生成的 Markdown 里插入<br>标签。这在渲染时没问题，但如果你把这份 Markdown 拿到别的平台发布，某些平台的安全过滤器会直接把<br>过滤掉，导致表格里的换行消失。
我的处理方式是，遇到表格内需要折行的场景，尽量只放短语或代码片段，不放长段落。长段落拆到表格外面的正文区域写，或者改用引用块搭配列表来组织信息，完全绕开<br>的兼容性问题。
4.2 Git 协作时 CRLF 换行符引发的震荡
这个坑不是 Markweave 独有，但因为它默认你直接编辑源文件，所以坑得比较深。在 Windows 上，Markweave 默认保存文件时会带上\r\n，在 macOS 和 Linux 环境下则保留为\n。如果你在一台 Windows 机器上用它写完文档，提交到 Git 仓库，然后队友在 macOS 上打开，Git 的autocrlf设置如果没配好，整个文档会被判定为"全部行都有变动"，diff 出来一团糟。
后来我统一在项目根目录加了.gitattributes文件，声明*.md text eol=lf，并且把 Markweave 的保存设置里换行符改成了 LF。这样无论在哪台机器上编辑，提交到仓库里的 Markdown 文件始终是 LF，diff 就干净了。如果你正在用 Markweave 写个人笔记且不同步到 Git，倒不用操心这个。
4.3 大文档的性能与自动保存机制
Markweave 对单文档大小的容忍度，我的实测是在 2 万字以内表现良好，超过 5 万字的长文（比如写整本电子书或者毕业论文）会出现两个问题：一是大幅度的滚动时渲染会有肉眼可见的迟滞；二是自动保存触发时，如果文档里图片是 base64 内嵌的，保存操作会造成短时间的界面卡顿。
这里建议用 Markweave 处理超大文档时，把图片改为外链路径，不要直接粘贴嵌入。同时开启自动保存后，把间隔时间调成 30 秒左右，既能保证不丢稿，也不会因为保存太频繁打断心流。我已经把写长篇技术教程的流程改成"单个章节一个文件"，用 Markweave 写内容，最后再用脚本把所有章节拼接成一篇大文档，这样就把单文件性能问题绕开了。
5. 和主流编辑器放一起比一比：Markweave 的定位与选型建议
5.1 与 Typora、Obsidian、Notion 的横向对比
把这四样东西放一起，出发点完全不同，但用户在选择时确实会纠结。我自己的体会是，按"对 Markdown 源文件的控制力"排序是：Markweave > Typora ≈ Obsidian > Notion。
Typora 是 Markweave 最直接的竞争对手。两者在"即时渲染"这一核心交互上高度相似，但 Typora 是闭源的，主题生态成熟，Markweave 是开源的，有自己独特的 API 扩展能力。在写作体验的打磨上，Typora 经过多年迭代细节更细腻，Markweave 则在功能的透明度和可定制性上占优。
Obsidian 也可以做到所见即所得，但它的根基是"知识库双向链接"，强调笔记之间的网状关联，编辑器只是它整个系统的一个模块。而 Markweave 更纯粹，它就是要当一款称职的 Markdown 编辑器，做深这一件事。
Notion 的 WYSIWYG 体验极佳，但底层是数据库模型，内容天然绑定在它的服务里。如果你追求"所有笔记都是纯文本的 .md 文件，换个工具随时带走"，Notion 从一开始就不在一个赛道上。
以下是几个维度的直观对比：
| 维度 | Markweave | Typora | Obsidian | Notion |
|---|---|---|---|---|
| 开源 | 是 | 否 | 部分插件开源 | 否 |
| 源文件格式 | 纯 Markdown | 纯 Markdown | 纯 Markdown / 库结构 | 私有块结构 |
| WYSIWYG 模式 | 即时渲染 | 即时渲染 | 阅读与编辑循环 | 全 WYSIWYG |
| 离线优先级 | 高 | 高 | 高 | 低 |
| 扩展性 | 可编程 API | 主题+插件有限 | 极强 | 数据库视图丰富 |
| 数据迁移成本 | 极低 | 低 | 低 | 高 |
5.2 哪些场景下我更推荐 Markweave
如果你符合以下任一条件，Markweave 大概率是合适的：
- 你在写技术博客或工作日志，最终产物要求发布到 GitHub Pages、VitePress 或其他静态站点系统，需要文档格式与 Markdown 源结构保持一致；
- 你参与的开源项目要求文档贡献者用 Markdown 规范格式，而你希望在编辑时直接看到效果，不需要一遍遍切预览；
- 你受不了某些在线文档平台对 Markdown 表格、公式、页内锚点的阉割，想掌控每一个语法细节；
- 你希望整个写作工具链里每一条数据都能用
grep搜索、能进 Git 比对、能用脚本批量处理。
在我的实际使用中，Markweave 的跨平台和轻量是它最强的两个特质。它的桌面客户端和网页端体验一致，数据文件完全由我掌握，没有云同步绑定问题。同时它支持给不同工作区设置不同的配置，比如我在写博客的项目里关闭了拼写检查，在写技术方案的项目里打开了行号显示和自动保存。
5.3 在团队协作场景里的角色定位
Markweave 不是协作文档工具，它没有多人实时编辑能力。这看上去是个短板，但换个角度看，反而不失为一种优点。团队技术方案评审时，Markweave 负责产出规范的 Markdown 源文档，之后用 GitHub 或 GitLab 的 merge request 流程去做审阅和评论。这样协作链路非常清晰：编辑发生在本地，评审发生在代码托管平台，合并后以文档站形式发布。
我在团队内部推行这套流程已有几个月，体验最明显的好处是彻底解决了"文档内容各改各的，最后版本对不上"的问题。因为每个.md文件都走 Git 版本管理，哪一行是谁、什么时候、为什么改的，一目了然。虽然 Markweave 本身不做协作，但它天然适配 Git 为中心的协作体系，这一点其实是很多商业化协作文档做不到的。
最后再分享一下我的个人使用习惯
用了一段时间 Markweave 之后，我的桌面已经看不到"双栏编辑器"了。每天打开它以 Markdown 格式记录工作日志，随手写一些代码草稿，周末把一周的要点整理成博客文章。它的确是开源的，项目里可以直接看到解析器和编辑器引擎的源码，这对于喜欢折腾编辑器行为的人来说是个宝库。如果你也在找一个"所见即所得、数据还完全在自己手里"的 Markdown 写作工具，值得趁周末花一小时装上试试，把它跟手头的编辑器对比跑一遍，说不定就是你在找的那个。
