1. 为什么我又把 Markdown 编辑器换回了开源方案用了几年 Typora从 0.11 的免费测试版一路跟到 1.x 正式收费说实话体验一直不错。但每次换电脑、重装系统激活这件事就让人头疼——序列号要翻邮箱找换设备还得先反激活偶尔还会遇到激活状态失效、弹窗提示重新验证的情况。更别提团队协作时同事用 Linux、我用 Windows、还有人用 macOS授权策略各不相同沟通成本比写文档本身还高。后来我开始认真找 Typora 的平替试过 VS Code 加插件、试过 Obsidian、试过几款网页版编辑器各有各的问题要么太重要么实时预览和源码模式切换不顺手要么对 Mermaid、KaTeX 这类扩展语法支持不完整。直到用上SoloMD才算找到一个真正能无痛迁移的方案——开源、免费、跨平台Windows、macOS、Linux 三端都能跑核心的所见即所得编辑体验和 Typora 非常接近而且 Mermaid 图表、KaTeX 数学公式这些高频需求全都原生支持。这篇文章不是官方文档的搬运而是我实际用 SoloMD 替换 Typora 之后从安装、配置、语法兼容、图表渲染到日常写作流程的完整复盘。如果你也在纠结 Typora 的授权问题或者单纯想找一个更自由、可定制的 Markdown 编辑器下面这些内容应该能帮你少走弯路。我会把踩过的坑、参数配置、以及那些文档里不会写的细节都摊开讲尽量让不同基础的人都能直接抄作业。2. SoloMD 到底解决了 Typora 用户的哪些真实痛点2.1 授权与跨平台从激活焦虑到装完即用Typora 的收费模式本身没问题15 美元买断三台设备对重度用户来说不算贵。但问题在于它的授权验证机制对多设备用户不太友好。我自己有三台常用机器一台 Windows 台式、一台 macOS 笔记本、一台 Linux 开发机。每次在其中一台激活另一台就可能掉线需要手动反激活再重新激活。更麻烦的是某些系统更新或硬件变更后激活状态会莫名其妙失效然后就是那个熟悉的弹窗。SoloMD 作为开源项目直接绕开了这一整套授权逻辑。下载对应平台的安装包装完打开就能用没有任何登录、激活、序列号的概念。对于经常折腾系统、换设备、或者在虚拟机里写文档的人来说这个差异是决定性的。而且开源意味着代码可审计不用担心后台偷偷上传文档内容——这一点对写敏感技术文档的人尤其重要。跨平台方面SoloMD 在三大桌面系统上的表现基本一致。我实测下来Windows 版和 macOS 版的界面布局、快捷键、渲染效果几乎无差别Linux 版在 Ubuntu 22.04 和 Fedora 38 上也能正常跑只是某些系统级字体渲染略有差异后面会细说。2.2 实时预览与源码模式的切换逻辑Typora 最让人上瘾的就是所见即所得——你打字的时候Markdown 语法符号会自动隐藏或弱化看到的就是接近最终渲染的效果。SoloMD 在这点上做了类似的实现但切换逻辑稍有不同需要适应一下。Typora 是无缝混合模式光标所在行显示源码其他行显示渲染结果。SoloMD 默认也是这个思路但它额外提供了一个分栏预览模式左边源码右边渲染适合需要精确控制格式的场景。我个人的习惯是日常写作开混合模式调表格和复杂 Mermaid 图的时候切到分栏模式因为分栏模式下源码和渲染结果一一对应改起来更直观。这里有个细节值得注意SoloMD 的混合模式在遇到嵌套列表或复杂表格时偶尔会出现光标定位偏移尤其是列表项里嵌代码块的时候。我的应对方法是先写完结构再回头填内容避免边写边调格式。这个坑 Typora 早期版本也有后来优化了SoloMD 目前还在迭代中。2.3 Mermaid 与 KaTeX技术写作的刚需支持对技术博主来说Markdown 编辑器能不能原生渲染 Mermaid 和 KaTeX直接决定了工作流是否顺畅。Typora 对这两者的支持是后来才加上的早期版本需要装插件或者导出后另找工具渲染。SoloMD 从一开始就把这两个作为核心特性来做实测下来完成度相当高。Mermaid 方面SoloMD 支持流程图、时序图、ER 图、思维导图、甘特图等主流图表类型。我写技术方案时最常用的是流程图和 ER 图SoloMD 的渲染速度和 Typora 基本持平复杂图表超过 50 个节点会有一两秒的延迟但不会卡死。KaTeX 方面行内公式和块级公式都能正常渲染希腊字母、矩阵、积分符号这些都没问题渲染质量比某些网页版编辑器用的 MathJax 更清爽。不过有个坑要提前说SoloMD 的 Mermaid 版本可能比 Typora 内置的略旧某些新语法比如mindmap的某些配置项可能不支持。如果你重度依赖 Mermaid 新特性建议先拿一个测试文档跑一遍确认语法兼容性再迁移。3. 从 Typora 迁移到 SoloMD 的完整操作路径3.1 安装包选择与系统依赖处理SoloMD 的安装包在开源仓库的 Releases 页面可以找到三大平台都有对应的安装文件。Windows 是.exe或.msimacOS 是.dmgLinux 提供.AppImage、.deb和.rpm三种格式。我的建议是Windows 用户优先选.msi安装后会自动注册文件关联双击.md文件就能用 SoloMD 打开。macOS 用户下载.dmg后拖进 Applications 即可首次打开可能需要在系统设置 - 隐私与安全性里允许一下这是 macOS 对非商店应用的常规限制。Linux 用户如果用的是 Ubuntu/Debian 系直接装.deb最省事Fedora/RHEL 系用.rpm不想动系统包管理的可以用.AppImage给个执行权限就能跑。Linux 下有个依赖问题要注意SoloMD 基于 Electron 构建需要系统有libgtk-3、libnss3、libasound2这些基础库。大部分桌面发行版默认都有但如果你用的是最小化安装的服务器版或者 Docker 环境需要手动补装。我曾在 Ubuntu Server 上试过跑 SoloMD补了五六个依赖才起来后来发现没必要——服务器上直接用命令行工具处理 Markdown 更合适GUI 编辑器还是留给桌面环境。3.2 首次启动的配置项与偏好设置装完第一次打开SoloMD 会问你要不要导入已有配置。如果你之前用 Typora可以跳过这一步因为两者的配置文件格式不兼容手动设置更靠谱。我建议按下面的顺序过一遍偏好设置编辑器设置里把默认打开模式设为混合预览字体选一个等宽字体我用的是 JetBrains MonoWindows 上也可以用 Consolas字号调到 15-16px行高 1.6 左右长时间写作眼睛不容易累。Markdown 设置里确认启用 Mermaid和启用 KaTeX都勾上。这两个默认是开的但有些版本更新后可能会重置检查一下不亏。另外把自动保存打开间隔设成 30 秒或 1 分钟避免意外崩溃丢内容。外观设置里SoloMD 内置了几套主题浅色和深色都有。我白天用浅色晚上切深色切换入口在右下角状态栏比 Typora 藏得浅这点好评。如果你对主题不满意SoloMD 支持自定义 CSS后面会讲怎么改。图片设置是个重点。Typora 用户最关心的图片怎样调整大小在 SoloMD 里也有对应方案。SoloMD 支持两种图片处理模式一是复制到指定文件夹二是转 Base64 内嵌。我推荐用第一种在设置里指定一个统一的图片存放目录比如./assets这样文档和图片分离迁移和备份都方便。调整图片大小用标准 HTML 语法img src... width500即可SoloMD 能正确渲染。3.3 快捷键映射与肌肉记忆迁移从 Typora 切过来最大的不适应来自快捷键差异。Typora 的快捷键设计比较独特SoloMD 更接近通用编辑器习惯。下面这张表是我整理的高频操作对照建议打印出来贴显示器边上一周就能形成新肌肉记忆操作Typora 快捷键SoloMD 快捷键备注加粗Ctrl/Cmd BCtrl/Cmd B一致斜体Ctrl/Cmd ICtrl/Cmd I一致插入链接Ctrl/Cmd KCtrl/Cmd K一致插入代码块Ctrl/Cmd Shift KCtrl/Cmd Shift C需适应插入表格Ctrl/Cmd TCtrl/Cmd Shift T需适应切换源码模式Ctrl/Cmd /Ctrl/Cmd E需适应大纲面板Ctrl/Cmd Shift 1Ctrl/Cmd Shift O需适应搜索Ctrl/Cmd FCtrl/Cmd F一致实测下来最需要重新练的是切换源码模式和插入代码块这两个。我大概用了三天才不再按错。如果你实在改不过来SoloMD 支持自定义快捷键在设置里可以逐个改回 Typora 的方案但我不建议这么做——通用快捷键在别的编辑器里也能用长期看更划算。4. Mermaid 图表在 SoloMD 里的实战渲染细节4.1 流程图与思维导图的语法兼容性测试Mermaid 是技术写作里提升表达效率的利器一张流程图能顶三段文字描述。SoloMD 对 Mermaid 的支持基于内置的渲染引擎我用实际项目里的图表做了兼容性测试结果如下流程图flowchart完全兼容graph TD、graph LR这些方向声明都正常节点形状矩形、圆角、菱形、圆形和连线样式实线、虚线、粗线都能渲染。我写架构文档时常用的子图subgraph也没问题嵌套两层以内渲染正常三层以上布局会有点挤建议拆成多张图。思维导图mindmap支持但要注意缩进语法。Mermaid 的 mindmap 用缩进表示层级SoloMD 对 Tab 和空格的处理和 Typora 略有不同——Typora 里 Tab 和空格混用有时也能渲染SoloMD 要求统一用空格且每层缩进两个空格。我踩过一次坑从 Typora 复制过来的思维导图代码因为混了 TabSoloMD 直接报语法错误改成纯空格后正常。ER 图erDiagram支持良好实体、属性、关系基数一对一、一对多都能正确渲染。我用来画数据库表结构比手写表格清晰得多。唯一要注意的是实体名和属性名里不要用中文标点否则解析会出问题。时序图sequenceDiagram支持参与者、消息、激活框、循环、条件分支都能渲染。复杂时序图超过 10 个参与者建议拆图否则横向会溢出需要手动滚动。4.2 渲染性能与复杂图表的优化策略Mermaid 图表的渲染性能是很多人关心的问题。我拿一个包含 60 个节点、80 条连线的流程图做了测试SoloMD 首次渲染大约 1.5 秒之后编辑其他内容时图表不会重新渲染只有修改图表代码块本身才会触发重绘。这个策略比某些编辑器每次按键都重绘要聪明得多写作体验流畅不少。如果你的图表特别复杂渲染慢到影响写作我有几个优化建议拆图把一张大图拆成两三张小图用文字串联。读者看起来也更轻松。简化节点文字节点里写关键词详细说明放正文。Mermaid 渲染时文字换行和布局计算很耗性能。避免过度嵌套子图子图嵌套超过两层布局算法复杂度指数上升。用%%注释掉暂时不看的图表SoloMD 会跳过注释块不渲染。另外SoloMD 的 Mermaid 渲染是在编辑器内实时进行的导出 PDF 或 HTML 时会重新渲染一遍。如果你导出后发现图表和编辑器里看到的不一样通常是导出时的页面宽度不同导致的布局变化调整图表方向比如从LR改成TD往往能解决。4.3 导出 PDF 时 Mermaid 图表的常见问题导出 PDF 是技术文档的刚需但 Mermaid 图表在 PDF 里的表现经常出问题。我实测下来SoloMD 导出 PDF 时 Mermaid 图表可能出现三种情况第一种是图表被截断。原因是图表宽度超过了 PDF 页面宽度。解决办法是在导出设置里把页面尺寸调大或者把图表方向从横向改成纵向。我一般用 A4 纵向图表宽度控制在 800px 以内。第二种是文字模糊。这是矢量图转位图时的分辨率问题。SoloMD 导出 PDF 时可以选择高质量模式图表会以更高 DPI 渲染文字清晰度明显提升。这个选项在导出对话框的高级设置里默认可能没开记得手动勾上。第三种是图表位置偏移。偶尔图表会跑到页面边缘甚至被裁掉。这通常是 Mermaid 布局算法和 PDF 分页逻辑冲突导致的。我的应对方法是在图表前后各加一个空行给渲染引擎留出缓冲空间如果还不行把图表单独放在文档末尾导出后用 PDF 工具合并。提示导出前先用打印预览功能检查一遍比导出后再打开 PDF 检查快得多。SoloMD 的打印预览和 PDF 导出用的是同一套渲染逻辑预览没问题基本就稳了。5. KaTeX 数学公式与图片处理的细节打磨5.1 行内公式与块级公式的书写规范KaTeX 是 SoloMD 处理数学公式的核心引擎相比 MathJax它的渲染速度更快输出更干净。但 KaTeX 对语法要求比 MathJax 严格一些在 MathJax 里能跑的野路子写法在 KaTeX 里会直接报错。行内公式用单个美元符号包裹比如$E mc^2$渲染后就是 $E mc^2$。块级公式用双美元符号包裹单独成行$$ \int_{-\infty}^{\infty} e^{-x^2} dx \sqrt{\pi} $$渲染后是$$ \int_{-\infty}^{\infty} e^{-x^2} dx \sqrt{\pi} $$我踩过的坑主要有两个一是中文和公式混排时公式前后的空格处理。KaTeX 要求美元符号和中文之间最好有空格否则某些情况下解析会出错。二是多行公式的对齐KaTeX 用aligned环境不是align写错了会报Undefined control sequence。对于经常写数学公式的人我建议把常用公式做成代码片段用编辑器的插入片段功能快速调用。SoloMD 支持自定义代码片段在设置里可以配置触发词和展开内容比每次手打快得多。5.2 图片插入、缩放与路径管理的实操方案图片处理是 Markdown 写作里最琐碎也最容易出问题的环节。Typora 用户经常问图片怎样调整大小SoloMD 的答案和 Typora 类似用 HTML 的img标签加width属性。img src./assets/diagram.png width600 alt架构图但这里有个路径管理的坑。如果你用相对路径./assets/文档移动位置后图片就会失效。我的做法是在 SoloMD 设置里指定一个全局图片目录所有文档的图片都存到同一个地方用绝对路径引用。这样文档随便移动图片都不会丢。缺点是备份时要记得把图片目录一起备份。另一个方案是用 Base64 内嵌图片直接编码进 Markdown 文件单文件自包含迁移零负担。但 Base64 会让文件体积膨胀约 33%而且编辑器打开大文件时会变慢。我只在写短文档、需要单文件分享时用这个方案。图片缩放除了width还可以用height但建议只指定一个维度另一个让浏览器按比例自动计算避免图片变形。如果要对图片加边框或圆角可以用style属性img src./assets/screenshot.png width500 styleborder: 1px solid #ccc; border-radius: 4px;SoloMD 能正确渲染这些内联样式导出 HTML 和 PDF 时也会保留。5.3 主题自定义与 CSS 微调SoloMD 内置主题够用但如果你想让它看起来更像 Typora 的某个主题或者匹配个人博客的配色可以自定义 CSS。入口在设置里的外观 - 自定义 CSS打开后是一个代码编辑器你写的样式会覆盖默认主题。我自己的做法是只改几个关键变量正文字体、代码块背景色、链接颜色、标题间距。下面是我用的一段 CSS效果是让正文更接近 Typora 的 GitHub 主题风格body { font-family: JetBrains Mono, PingFang SC, Microsoft YaHei, sans-serif; font-size: 16px; line-height: 1.7; color: #24292e; } code { background-color: #f6f8fa; padding: 2px 6px; border-radius: 3px; font-size: 0.9em; } a { color: #0366d6; text-decoration: none; } a:hover { text-decoration: underline; }改完 CSS 后需要重启 SoloMD 才能生效这点和 Typora 一样。如果你不确定某个元素的类名可以用开发者工具Ctrl/Cmd Shift I查看SoloMD 基于 Electron开发者工具和 Chrome 一样。注意自定义 CSS 在导出 PDF 时也会生效但某些打印专用的样式比如media print需要单独写。如果你导出的 PDF 和编辑器里看到的不一样检查一下是不是打印样式覆盖了屏幕样式。6. 日常写作流中的效率技巧与踩坑记录6.1 文件管理与多文档切换的顺手方案SoloMD 没有内置的库或工作区概念它就是一个单文档编辑器打开一个文件编辑一个文件。这对习惯 Typora 单文档模式的用户来说很自然但如果你要管理几十篇文档就需要一点技巧。我的方案是用系统文件夹组织文档然后在 SoloMD 里用最近打开列表快速切换。SoloMD 的最近文件列表可以保留 20 条记录够日常用了。另外SoloMD 支持多窗口你可以同时打开多个文档用系统任务栏切换。我写系列文章时会把相关文档都打开用 AltTab 在窗口间跳。如果你需要更强的文档管理可以配合外部工具。我在 macOS 上用 AlfredWindows 上用 EverythingLinux 上用 fzf都是快速定位文件的工具找到后用 SoloMD 打开。这样 SoloMD 专注编辑文件管理交给更专业的工具各司其职。6.2 自动保存与版本备份的配置建议自动保存是保命功能但光有自动保存还不够你还需要版本备份。SoloMD 的自动保存是覆盖式的保存后旧版本就没了。如果误删了内容又已经自动保存就找不回来了。我的做法是文档根目录用 Git 管理每次写完一个阶段就 commit 一次。SoloMD 不直接集成 Git但你可以用外部工具比如 VS Code 的 Git 面板或者命令行来提交。这样每个版本都有记录误删了随时回滚。如果你不想用 Git至少要做到另存为习惯重要文档在重大修改前先手动另存一个带日期的副本比如article-2024-01-15.md。这个习惯看起来笨但关键时刻能救命。我就靠这个办法找回了一篇被自动保存覆盖了半截的文章。6.3 那些官方文档不会告诉你的小坑最后分享几个我在使用 SoloMD 过程中踩过的坑官方文档里不会写但实际用起来很影响体验坑一中文输入法下的快捷键冲突。在某些 Linux 桌面环境下中文输入法会拦截 CtrlShift 组合键导致 SoloMD 的快捷键失效。解决办法是在输入法设置里把冲突的快捷键改掉或者把 SoloMD 的快捷键改成不常用的组合。坑二大文件打开慢。超过 5000 行的 Markdown 文件SoloMD 打开时会明显卡顿因为混合预览模式要实时渲染所有内容。我的应对方法是大文件先用源码模式打开编辑完再切回混合模式预览。或者把大文件拆成多个小文件用链接串联。坑三Mermaid 图表里的特殊字符。节点文字里如果包含()、[]、{}这些字符需要用引号包裹否则解析会出错。比如A[计算 (xy)]要写成A[计算 (xy)]。这个规则 Typora 和 SoloMD 都一样但很容易忘。坑四导出 HTML 时图片路径问题。导出 HTML 时如果图片用的是相对路径导出的 HTML 文件必须和图片保持相对位置关系否则图片显示不出来。解决办法是导出时选择内嵌图片或者导出后手动调整图片路径。坑五主题切换后代码块高亮失效。某些自定义主题没有定义代码高亮的配色切换后代码块会变成纯黑白。解决办法是在自定义 CSS 里补上代码高亮的样式或者换一个完整的主题。这些坑我都踩过有些折腾了很久才找到原因。写出来是希望后来的人能少花点时间在工具上多花点时间在内容上。SoloMD 作为一个开源项目迭代速度不慢有些问题可能在你看到这篇文章时已经修复了但了解这些坑的存在至少能在遇到问题时知道往哪个方向排查。用了几个月 SoloMD 之后我最大的感受是工具的自由度比功能的丰富度更重要。Typora 功能确实打磨得更精致但 SoloMD 给的是一种不被绑定的安心感——不用担心激活失效不用担心换设备不用担心项目哪天停止维护。对于把 Markdown 当作长期写作格式的人来说这种安心感值得用一点点体验上的粗糙来换。