Markdown 这门手艺我第一次接触时觉得它土得掉渣——一堆星号、井号堆在纯文本里看着像开源项目的说明书。但用到现在我电脑里几乎所有文档、笔记、需求说明、周报、甚至给客户的技术方案底层都是 Markdown 源文件而 Typora 则是我打开这些文件的第一选择。原因很简单它把“写作”和“排版”这两件本该分开的事重新合到了一起左边不用再挂一个预览窗口光标落下去的地方就是最终的样子。这篇东西写给三类人刚听说 Markdown、想找个编辑器上手的新人被 Word 格式折磨过、想换个工作流的上班族以及已经会用但总觉得“差点意思”、想把这套工具吃透的老用户。我会从选型逻辑、安装配置、语法重点、工作流串接一直讲到踩坑排查尽量把该说的细节都摊开。1. 为什么我最后把主力编辑器定成了 Typora1.1 Markdown 真正解决的痛点是什么先说 Markdown 本身。很多人把它理解成“一种简化版的富文本”这个理解不太准。Markdown 的本质是纯文本加轻量标记文件本身是.md用记事本打开就是一串可读的字符。星号代表强调井号代表标题竖线代表表格列这些符号不带任何样式信息只表达“这段内容在结构上是什么”。这个设计带来的好处本质上是把内容和呈现解耦了。你可以把 Markdown 想象成一份菜谱菜谱上写的是“盐 3 克、火候中火”至于最后装盘是在白瓷盘还是黑陶盘里那是餐厅的事跟菜谱无关。Word 不一样Word 是把菜谱、盘子、桌布、灯光全塞进一个文件里所以你换台电脑打开字体可能变了、行距可能变了、目录页码可能全乱。具体到实际使用Markdown 解决的是这几类高频问题跨平台迁移同一份.md文件在 Windows、macOS、Linux、手机端都能打开内容一个字不变。版本对比纯文本做 diff 非常干净Git 能精确告诉你改了哪一行Word 的二进制格式基本做不到。格式无损粘贴从 Markdown 转到 HTML、PDF、Word、PPT 大纲都属于“换一种渲染方式”源文件不动。长期可读十年后 Word 版本可能都换了好几轮.md文件用任何文本编辑器都能打开。我自己的工作场景里需求文档写完直接扔进 Git 仓库产品经理改了哪一句我一眼能看到这种体验是 Word 给不了的。1.2 Typora 的即时渲染改变了什么Markdown 编辑器大致分两派。一派是“源码 双栏预览”左边写原始标记右边实时渲染出效果代表是 VS Code 装 Markdown 插件、早期的一众网页编辑器。另一派是“即时渲染”也就是你打在编辑区里的内容直接就是渲染后的样子标记符号会被隐藏或弱化Typora 属于后者也是把它做火的那一个。这两种方式上手后感受差异很大。双栏预览的问题在于视线要来回跳你写一句“这里要加粗”左边看到的是四个星号右边看到的是加粗文字判断效果得靠眼睛在两侧之间切换。写短文档没问题写三五千字的长文时这种切换会不断打断心流。Typora 的做法是你输入**之后星号自动隐藏光标之后的文字直接变粗你输入#之后这一行立刻变大变成一级标题的样式。整个过程只有一个焦点区域眼睛不用移动。这个体验听起来只是省了几次转头但实际写作时的连贯性提升非常明显尤其是写技术文档这种需要频繁插入代码块、表格、公式的内容。注意即时渲染不代表你不需要懂语法。符号被隐藏了但文件里存的是实打实的标记。哪天你把文件拿到 VS Code 或 GitHub 上打开看到的还是原始符号。所以语法该学还得学。1.3 这套组合适合谁不适合谁我不太喜欢无脑推荐工具任何工具都有边界。下面这张表是我按实际使用经验整理的适配判断你可以直接对号入座。使用场景适配程度说明技术文档、API 说明、README很合适代码块、表格、公式支持完整个人笔记、知识库很合适纯文本便于搜索、备份、迁移公众号、知乎长文草稿合适写完后导出 HTML 再粘贴需求文档、方案评审稿合适配合 Git 做版本管理排版要求极高的印刷物料不太合适建议另用专业排版工具需要复杂批注和修订痕迹的合同不太合适这类协作 Word 更成熟大量图表的财务报告一般复杂图表建议用专门工具出图再插入一句话总结内容为主、格式为辅的场景Markdown 占优格式本身就是交付物核心的场景别勉强。2. 从下载到顺手安装配置这一关别省2.1 安装包获取与路径选择安装包认准官方站点 typora.io其他渠道拿到的安装包版本混乱出了奇怪问题很难排查。Windows 版是标准的 exe 安装程序macOS 是 dmg 拖拽安装Linux 官方提供 deb 和 AppImage 两种形式deb 适合 Debian/Ubuntu 系AppImage 免安装、扔哪儿都能跑。这里有一个小细节值得提前说安装路径和文档存放路径都尽量别用中文和空格。Markdown 里引用图片用的是相对路径如果目录名带中文或空格某些导出流程、命令行工具处理时容易出问题尤其你后面接了自动化脚本的时候。我自己的习惯是把所有笔记放在D:/notes/这种纯英文目录下层级也保持浅一点。另外建议把.md文件默认关联到 Typora。双击就能打开省去每次右键选程序的麻烦。如果同时用 VS Code 写代码可以让.md默认走 TyporaVS Code 里照常右键打开就行互不冲突。2.2 首选项里必须动的那几项装完别急着写先花五分钟把偏好设置过一遍。下面几项是强烈建议调整的设置项位置建议值理由自动保存通用开启避免断电、崩溃丢内容恢复未保存的草稿通用开启崩溃后能找回默认编码通用UTF-8跨平台兼容避免中文乱码换行符通用/编辑器按平台选择Windows 用 CRLF跨平台协作用 LF拼写检查编辑器按需写中文时误报多可关代码块自动换行Markdown关闭保持代码原样便于复制行内公式Markdown开启支持$...$写法其中编码和换行符这两项最容易被忽略也最容易埋雷。中文乱码十有八九是编码不统一导致的换行符则是团队协作时最容易产生无意义 diff 的地方——同一个人在不同系统上改同一个文件Git 会显示出整篇文件都被修改了实际内容只改了一个字。遇到这种情况先检查换行符设置八成是它在作怪。2.3 主题、字体与阅读宽度调优Typora 自带若干套主题默认主题偏素长时间盯着还行但长时间写代码块会觉得区分度不够。社区有大量主题包下载后扔进主题文件夹即可切换菜单里可以直接打开主题文件夹路径。这些主题本质上就是几个 CSS 文件懂一点样式的话完全可以自己改。我实际改过的几个地方供你参考正文字体换成带中文优化的字体中英文混排时字重更协调行高建议设在 1.7 到 1.9 之间。阅读宽度默认正文区宽度偏宽一行的字数太多眼睛从行尾回到行首很累。把内容区最大宽度收窄到 680px 到 760px 区间接近纸质书的阅读节奏。代码块背景调成低对比度的浅灰避免深色块在文档里太跳。标题间距段前段后的留白加大一点长文的结构感会强很多。具体做法是打开主题文件夹编辑对应的 CSS 文件改#write选择器下的max-width、font-family、line-height这些属性。改之前记得先把原文件备份一份改崩了能退回来。2.4 图片存储策略这一步决定你以后会不会返工这是整个配置环节里我觉得最值得花时间的一件事因为一旦前期处理不当等你写了上百篇带图的文档再想调整返工量是灾难级的。Markdown 引用图片写的是路径路径分两种绝对路径和相对路径。绝对路径长这样C:/Users/xxx/Pictures/a.png看着没问题但只要文件一移动、换台电脑、发给了别人图全部裂掉。相对路径则是./assets/a.png只要图片跟着文档目录一起走到哪儿都能显示。Typora 有一个专门针对这个问题的功能在偏好设置的“图像”面板里可以设置插入图片时自动复制到指定目录通常设成./assets或者./${filename}.assets这种形式。这样你从剪贴板粘贴一张截图它会自动存到文档旁边的资源文件夹路径自动写成相对路径全程不用手动管理。顺手再勾上“优先使用相对路径”。这一步做完你的文档就变成了一个自包含的文件夹一个.md文件加一个同名资源目录拷到任何地方都能正常显示。提示如果不是单篇文档而是一个完整的笔记库可以把所有图片统一收在一个顶层assets目录里再用相对路径跨级引用。好处是去重方便、备份体积小代价是路径里会多几层../看源码时略乱。两种方案都能用关键是整个库内保持一致别一半用这套一半用那套。3. Markdown 语法够用、够稳、不容易忘的那一版3.1 标题、段落与那个绕不开的换行问题标题用井号几个井号就是几级标题最多六级。写法上有个约定俗成的细节井号后面最好加一个空格# 标题而不是#标题。不加空格在某些解析器里识别不出来。一级标题在一篇文档里通常只用一次就是文档标题正文里的结构从二级开始比较舒服。段落之间用空行分隔。这是 Markdown 里最重要的一条规则比任何符号都重要。你连续写几行文字解析器会把它们当成同一段中间渲染成一个空格只有空行才表示段落结束。很多人第一次用 Markdown 都觉得“我明明换行了怎么没换”原因就在这儿。如果确实需要在一个段落内强制换行有几种做法第一行结尾加两个空格 第二行跟在上面两个空格后面 第一行结尾加反斜杠\ 第二行 第一行 br 第二行用 HTML 标签兼容性最好但不够“纯”实测下来行尾两个空格是最通用的写法但它有个隐患很多编辑器会自动删除行尾空格包括某些代码规范检查工具所以协作场景下容易被清掉。\反斜杠更保险一些Typora 和主流解析器都支持。至于br属于兜底方案实在不行再用。我个人的规矩是段落一律用空行分开绝不依赖行尾空格只有在同段落内确实需要断行的场景比如诗歌、地址、代码注释才用反斜杠。3.2 列表、引用、代码块与转义无序列表用-或*开头加空格有序列表用1.开头加空格。嵌套靠缩进通常缩进两个或四个空格。这里建议整个文档统一用四个空格因为不同解析器对两空格的兼容性略有差异四空格最稳。任务列表是很多人不知道但非常好用的功能写法是- [ ] 待办和- [x] 已完成渲染出来是可勾选的方框。用它做需求清单、发布检查表非常顺手比单独列一堆文本直观得多。引用块用大于号开头可以嵌套常用于标注提示和注意事项。代码块用三个反引号包裹强烈建议在开头就写上语言名比如python、javascript、bash。原因有两个一是渲染时会有语法高亮读代码轻松很多二是很多工具包括一些文档站点生成器会读取这个语言标识用来决定怎么处理代码。写代码块时还要注意如果代码透本身包含三个连续反引号要用更长的反引号包围或者改用波浪线~~~。转义是个容易被忽略的点。如果你的正文里本来就需要显示*、#、_这些符号直接写会被解析器吃掉前面加反斜杠即可转义。比如想显示*不是斜体*就写成\*不是斜体\*。中英文混排时_和*特别容易被误伤尤其写变量名如file_name的时候如果两边各有一个下划线中间那段会被识别成斜体。解决办法是用反引号包起来写成行内代码file_name既避免误解析又能在视觉上和正文区分开。3.3 表格手写、对齐与表格互转表格是 Markdown 里手写最费劲的部分没有之一。基础语法是这样| 参数名 | 类型 | 默认值 | 说明 | | :--- | :---: | ---: | :--- | | timeout | number | 3000 | 超时时间毫秒 | | retry | boolean | false | 是否自动重试 | | mode | string | auto | 运行模式 |第二行是分隔行必须存在负责告诉解析器第一行是表头。冒号的位置决定对齐方式冒号在左边是左对齐两边都有是居中在右边是右对齐。这个对齐规则我建议不要省因为同一份文档在不同解析器下的默认对齐策略不一样写死了才稳定。手动写表格效率太低有几个省事的办法Typora 内置表格编辑插入表格后可以用快捷键在单元格之间跳转、插入行列不用手动敲竖线。从 Excel 复制在 Excel 里选中区域复制直接粘贴进 Typora多数情况下能自动转成 Markdown 表格这是我最常用的方式。表格转回 Excel反过来把 Markdown 表格复制进 Excel一般也能识别成表格结构如果不行先导出成 CSV 再打开。注意Markdown 表格不支持单元格合并也不支持单元格内换行除非借助 HTML。真要写复杂表格建议改用 HTML 表格或者干脆放一张图。别跟语法较劲工具不合适就换。表格宽度也是常被吐槽的点。列数一多源码里一行特别长编辑器不折行的话要横向滚动。建议把|之间的内容适当对齐留白源码可读性会好很多。有的格式化工具能自动对齐愿意折腾可以配一个。3.4 链接与图片路径那点事儿链接分两种写法[行内链接](https://example.com 鼠标悬停提示) [引用式链接][id] [id]: https://example.com 可选标题引用式链接适合同一地址在文内多处出现的情况改地址只需要改一处。写长文档时我基本都用引用式维护成本低。图片语法只比链接多一个感叹号方括号里的替代文字不能省。它的作用有三个图片加载失败时显示这段文字屏幕阅读器会读出来搜索引擎会作为索引依据。很多人图省事写这在无障碍和可访问性上是不合格的。图片大小控制在标准 Markdown 里没法直接设置要缩放得用 HTML 的img标签写 width 属性或者在 Typora 里用它自己支持的扩展语法。跨平台发布的话用 HTML 标签兼容性最好。3.5 数学公式与结构化图表Typora 对数学公式的支持是它能拿下技术写作人群的关键原因之一。行内公式用单个美元符号包裹块级公式用两个美元符号包裹并独占一行质能方程 $E mc^2$ 写在行内。 $$ \sum_{i1}^{n} i \frac{n(n1)}{2} $$块级公式可以多行书写也支持对齐环境。导出 PDF 时公式一般能正常渲染成矢量图形导出到某些不支持公式的平台则会退化这点后面工作流那一节会细说。至于流程图、时序图这类结构化图表Typora 内置了对相关文本描述语法的渲染支持写出来直接变成图。它的价值在于图表和文字放在同一个文件里改需求时图跟着改不会出现图文档不一致的情况。这块值得单独花时间研究我这里只提醒一点这类语法的渲染依赖解析器支持不是所有 Markdown 平台都能渲染出来往外发布前先确认目标平台是否兼容。4. 把 Typora 接进已有的工作流4.1 与代码编辑器、笔记本的分工Typora 不是万能的也没必要什么都用它。我的分工是这样Typora写正式文档、长文、方案、笔记需要长时间专注写作的场景。VS Code在项目仓库里改 README、写代码注释、需要同时看多个文件时。装 Markdown 插件后编辑体验也不差而且和代码在同一个窗口上下文切换成本低。Jupyter Notebook跑数据、做分析、需要代码和输出结果穿插呈现时。Notebook 的单元格本质上也是 Markdown写完的说明可以直接搬到 Typora 里。三个工具之间切换靠的就是.md这个通用格式。VS Code 里写的文档Typora 打开完全一致Typora 里写的说明段复制进 Jupyter 单元格也直接生效。这也是我前面反复强调“语法该学”的原因——格式通用才是效率的根源。4.2 导出Markdown 转 Word、PDF、HTMLTypora 的导出功能是它的隐藏实力。菜单里能导出 PDF、HTML、Word、EPUB、LaTeX、图片等多种格式。导出 Word 需要额外装 Pandoc这是个文档格式转换工具装完之后 Typora 会自动识别。导出时可以用默认模板也可以指定自定义的.docx参考模板——做法是先导出一份默认的在 Word 里把样式标题字体、正文字号、页边距改成你要的样子再作为模板导回去。这样每次导出都是统一格式特别适合需要定期交周报、月报的场景。导出 PDF 有两条路内置导出和走 Pandoc。内置的排版还原度高公式和图都能正常渲染走 Pandoc 的好处是可以配合 LaTeX 模板做更精细的排版代价是配置门槛高。这里有一个实操上的坑要提醒导出前先检查图片路径。如果文档里用了绝对路径的图片导出后发给别人对方打开就是一堆裂图。用相对路径加同目录资源文件夹的方案导出的 PDF 和 HTML 才能带着图走。还有一个常见需求是“转成 HTML 后粘贴到网页编辑器”。这时候注意多数平台会过滤掉一部分内联样式粘过去可能变形。稳妥做法是导出 HTML 后把导出的文件在浏览器里打开全选复制再粘贴到目标编辑器。这样比直接复制 Markdown 源文更保真。4.3 网页剪藏与格式互转写东西的人总在收集资料。常见需求是“看到一篇好文章想存成 Markdown 留着”。浏览器有一类剪藏扩展专门干这个把网页正文提取出来转成 Markdown图片按你的规则下载到本地或者保留外链。这类工具选型时看三点正文提取干不干净能不能自动去掉广告和导航、图片处理方式下载到本地还是保留链接、代码块和表格保留得完不完整。前两点决定可用性第三点决定技术类文章的质量。用过几款之后我的经验是技术博客的代码块是重灾区经常被提取成一堆散掉的文本拿回来还得手动修。另一个方向是各种文档格式往 Markdown 转。PDF 转 Markdown、Word 转 Markdown、HTML 转 Markdown 都有开源工具转换质量参差不齐。PDF 尤其难因为 PDF 本来就不是为“结构化文本”设计的它是为打印设计的表格和公式转出来经常是乱的。我的做法是结构性强的文档Word、HTML才值得自动转PDF 老老实实复制粘贴重排跟工具较劲的时间够你手打两遍了。4.4 笔记库组织与版本管理当文档数量上去之后组织方式是绕不开的问题。我的建议是尽量简单别一上来就搞复杂分类体系。一套我用了两年的目录结构供参考notes/ assets/ # 全局图片资源 inbox/ # 临时收集每周清空 01-docs/ # 正式文档、方案 02-notes/ # 学习笔记、读书笔记 03-snippets/ # 代码片段、常用配置 templates/ # 各种文档模板关键点在于inbox 目录。任何临时想法、剪藏的网页、没想好放哪儿的东西全部先扔进去每周固定时间清理一次归类或删除。没有这个缓冲你的库很快就会变成垃圾场。版本管理方面纯文本最大的优势就是可以直接上 Git。个人用的话本地建个仓库配一个免费托管平台的私有仓库定期 push 就行。好处是改错了一个字能翻回去误删了能恢复换电脑直接 clone 下来。用 Git 管笔记不需要懂复杂的分支操作掌握add、commit、push、log这四个命令基本够终身受用。5. 常见问题与排查实录5.1 排版类问题速查下面这张表是我在群里被问得最多的排版问题直接对照解决现象原因解决办法换行不生效两行黏在一起段间没空行段落之间加空行星号被吞掉没有加粗前后缺少空格或成对缺失确保**文字**两侧有空格变量名下划线变成斜体_被识别为强调标记用反引号包成行内代码表格渲染不出来缺分隔行或列数不匹配补上 井号标题没生效井号后缺空格改成# 标题列表嵌套错乱缩进不统一全文统一用四个空格缩进代码块里的内容被解析没用围栏包裹用三个反引号包裹并标注语言这类问题的共同点是几乎全部源于“符号和文字之间的空格”以及“空行”。Markdown 的解析器对空格很敏感写的时候养成“符号后面跟一个空格”的习惯能避免八成以上的排版问题。5.2 图片与路径类问题排查图片不显示是所有 Markdown 使用者都会遇到的坎排查顺序建议固定下来看路径类型。源码里是C:/...还是./...前者是绝对路径换环境必挂优先怀疑。看大小写。Linux 和部分服务器环境对文件名大小写敏感Image.png和image.png是两个文件。看是否带中文或空格。路径里只要有这两样某些工具链就会出问题建议统一改成英文加连字符。看图片是否真的存在。有时候是粘贴时没成功写入资源目录里根本没有这个文件。看导出目标。在编辑器里能显示导出后没了问题多半出在导出流程没把资源一起打包。我踩过最典型的一次坑用手机同步备份资料时只同步了.md文件忘了同步assets目录结果在新设备上全部显示裂图。从那以后我的规矩是文档和资源目录必须一起拷贝、一起备份永不分离。5.3 导出与字体类问题导出 PDF 时偶尔会遇到中文变成方框或者乱码这通常不是 Markdown 的问题而是导出工具用的字体里没有中文字形。排查思路分两步先确认系统里装了完整的中文字体集再检查导出配置里指定的字体名是否正确。走 Pandoc 导出的话可以在配置里显式指定中文字体。导出 Word 时如果样式混乱八成是没做参考模板。默认导出的样式比较朴素标题层级和正文没有明显区分。花二十分钟做一份自己的.docx模板能省下以后每次导出后的手动调格式时间。还有一个容易被忽略的点导出的文件体积。如果文档里嵌了大量高分辨率截图导出的 PDF 可能几十兆邮件都发不出去。养成习惯截图后用压缩工具过一遍或者截图时就把分辨率调低屏幕上看的文档 1000px 宽度足够了。5.4 我踩过的几个坑和几条私房经验最后这部分是我自己攒下来的文档里通常不写但用起来很实在。**第一条备份永远比技巧重要。**不管你用了多优雅的工作流只要没有备份一次误删就能让你损失半年的积累。我的方案是三层本地目录定期整包压缩、云端同步一份、Git 仓库一份。三层里任意两层同时挂掉才会真丢东西这个概率已经足够低了。**第二条别过早追求完美的工作流。**我见过太多人花两周研究目录结构和标签体系结果一篇笔记都没写。正确的顺序是先用最简陋的方式记起来记录量上来之后再根据实际痛点去优化结构。信息量不够的时候任何分类体系都是拍脑袋。**第三条模板比快捷键更省时间。**建几个常用模板——会议记录、周报、技术方案、读书笔记——每写一份新文档就复制一份模板改。比每次从空白页开始构思结构要快得多而且能保证同类文档格式统一。**第四条定期做一次“断舍离”。**每季度翻一遍自己的笔记库删掉过期内容、合并重复文档、把临时笔记整理成正式文档。这个过程一开始会心疼但你会发现自己真正有用的东西其实就那么几十篇剩下的都是噪音。库越干净检索越快用起来的意愿也越强。**第五条把长文拆成短文件。**一篇两万字的大文档打开慢、改起来提心吊胆、Git 冲突时几乎没法处理。我的做法是单个文件控制在三千字以内用目录索引文件把相关文档串起来。这样每个文件都能独立维护改动影响面小找内容也更快。说到底工具终究只是工具。Typora 也好别的编辑器也好它们解决的都只是“让写作这件事少一点摩擦”。真正决定产出质量的还是你脑子里有没有东西以及愿不愿意把它写清楚。我用了这么久最大的感受是一个好工具能让你愿意多写而多写本身才是唯一能把写作这件事变好的路径。
Markdown + Typora：即时渲染写作与文档工作流实战
Markdown 这门手艺我第一次接触时觉得它土得掉渣——一堆星号、井号堆在纯文本里看着像开源项目的说明书。但用到现在我电脑里几乎所有文档、笔记、需求说明、周报、甚至给客户的技术方案底层都是 Markdown 源文件而 Typora 则是我打开这些文件的第一选择。原因很简单它把“写作”和“排版”这两件本该分开的事重新合到了一起左边不用再挂一个预览窗口光标落下去的地方就是最终的样子。这篇东西写给三类人刚听说 Markdown、想找个编辑器上手的新人被 Word 格式折磨过、想换个工作流的上班族以及已经会用但总觉得“差点意思”、想把这套工具吃透的老用户。我会从选型逻辑、安装配置、语法重点、工作流串接一直讲到踩坑排查尽量把该说的细节都摊开。1. 为什么我最后把主力编辑器定成了 Typora1.1 Markdown 真正解决的痛点是什么先说 Markdown 本身。很多人把它理解成“一种简化版的富文本”这个理解不太准。Markdown 的本质是纯文本加轻量标记文件本身是.md用记事本打开就是一串可读的字符。星号代表强调井号代表标题竖线代表表格列这些符号不带任何样式信息只表达“这段内容在结构上是什么”。这个设计带来的好处本质上是把内容和呈现解耦了。你可以把 Markdown 想象成一份菜谱菜谱上写的是“盐 3 克、火候中火”至于最后装盘是在白瓷盘还是黑陶盘里那是餐厅的事跟菜谱无关。Word 不一样Word 是把菜谱、盘子、桌布、灯光全塞进一个文件里所以你换台电脑打开字体可能变了、行距可能变了、目录页码可能全乱。具体到实际使用Markdown 解决的是这几类高频问题跨平台迁移同一份.md文件在 Windows、macOS、Linux、手机端都能打开内容一个字不变。版本对比纯文本做 diff 非常干净Git 能精确告诉你改了哪一行Word 的二进制格式基本做不到。格式无损粘贴从 Markdown 转到 HTML、PDF、Word、PPT 大纲都属于“换一种渲染方式”源文件不动。长期可读十年后 Word 版本可能都换了好几轮.md文件用任何文本编辑器都能打开。我自己的工作场景里需求文档写完直接扔进 Git 仓库产品经理改了哪一句我一眼能看到这种体验是 Word 给不了的。1.2 Typora 的即时渲染改变了什么Markdown 编辑器大致分两派。一派是“源码 双栏预览”左边写原始标记右边实时渲染出效果代表是 VS Code 装 Markdown 插件、早期的一众网页编辑器。另一派是“即时渲染”也就是你打在编辑区里的内容直接就是渲染后的样子标记符号会被隐藏或弱化Typora 属于后者也是把它做火的那一个。这两种方式上手后感受差异很大。双栏预览的问题在于视线要来回跳你写一句“这里要加粗”左边看到的是四个星号右边看到的是加粗文字判断效果得靠眼睛在两侧之间切换。写短文档没问题写三五千字的长文时这种切换会不断打断心流。Typora 的做法是你输入**之后星号自动隐藏光标之后的文字直接变粗你输入#之后这一行立刻变大变成一级标题的样式。整个过程只有一个焦点区域眼睛不用移动。这个体验听起来只是省了几次转头但实际写作时的连贯性提升非常明显尤其是写技术文档这种需要频繁插入代码块、表格、公式的内容。注意即时渲染不代表你不需要懂语法。符号被隐藏了但文件里存的是实打实的标记。哪天你把文件拿到 VS Code 或 GitHub 上打开看到的还是原始符号。所以语法该学还得学。1.3 这套组合适合谁不适合谁我不太喜欢无脑推荐工具任何工具都有边界。下面这张表是我按实际使用经验整理的适配判断你可以直接对号入座。使用场景适配程度说明技术文档、API 说明、README很合适代码块、表格、公式支持完整个人笔记、知识库很合适纯文本便于搜索、备份、迁移公众号、知乎长文草稿合适写完后导出 HTML 再粘贴需求文档、方案评审稿合适配合 Git 做版本管理排版要求极高的印刷物料不太合适建议另用专业排版工具需要复杂批注和修订痕迹的合同不太合适这类协作 Word 更成熟大量图表的财务报告一般复杂图表建议用专门工具出图再插入一句话总结内容为主、格式为辅的场景Markdown 占优格式本身就是交付物核心的场景别勉强。2. 从下载到顺手安装配置这一关别省2.1 安装包获取与路径选择安装包认准官方站点 typora.io其他渠道拿到的安装包版本混乱出了奇怪问题很难排查。Windows 版是标准的 exe 安装程序macOS 是 dmg 拖拽安装Linux 官方提供 deb 和 AppImage 两种形式deb 适合 Debian/Ubuntu 系AppImage 免安装、扔哪儿都能跑。这里有一个小细节值得提前说安装路径和文档存放路径都尽量别用中文和空格。Markdown 里引用图片用的是相对路径如果目录名带中文或空格某些导出流程、命令行工具处理时容易出问题尤其你后面接了自动化脚本的时候。我自己的习惯是把所有笔记放在D:/notes/这种纯英文目录下层级也保持浅一点。另外建议把.md文件默认关联到 Typora。双击就能打开省去每次右键选程序的麻烦。如果同时用 VS Code 写代码可以让.md默认走 TyporaVS Code 里照常右键打开就行互不冲突。2.2 首选项里必须动的那几项装完别急着写先花五分钟把偏好设置过一遍。下面几项是强烈建议调整的设置项位置建议值理由自动保存通用开启避免断电、崩溃丢内容恢复未保存的草稿通用开启崩溃后能找回默认编码通用UTF-8跨平台兼容避免中文乱码换行符通用/编辑器按平台选择Windows 用 CRLF跨平台协作用 LF拼写检查编辑器按需写中文时误报多可关代码块自动换行Markdown关闭保持代码原样便于复制行内公式Markdown开启支持$...$写法其中编码和换行符这两项最容易被忽略也最容易埋雷。中文乱码十有八九是编码不统一导致的换行符则是团队协作时最容易产生无意义 diff 的地方——同一个人在不同系统上改同一个文件Git 会显示出整篇文件都被修改了实际内容只改了一个字。遇到这种情况先检查换行符设置八成是它在作怪。2.3 主题、字体与阅读宽度调优Typora 自带若干套主题默认主题偏素长时间盯着还行但长时间写代码块会觉得区分度不够。社区有大量主题包下载后扔进主题文件夹即可切换菜单里可以直接打开主题文件夹路径。这些主题本质上就是几个 CSS 文件懂一点样式的话完全可以自己改。我实际改过的几个地方供你参考正文字体换成带中文优化的字体中英文混排时字重更协调行高建议设在 1.7 到 1.9 之间。阅读宽度默认正文区宽度偏宽一行的字数太多眼睛从行尾回到行首很累。把内容区最大宽度收窄到 680px 到 760px 区间接近纸质书的阅读节奏。代码块背景调成低对比度的浅灰避免深色块在文档里太跳。标题间距段前段后的留白加大一点长文的结构感会强很多。具体做法是打开主题文件夹编辑对应的 CSS 文件改#write选择器下的max-width、font-family、line-height这些属性。改之前记得先把原文件备份一份改崩了能退回来。2.4 图片存储策略这一步决定你以后会不会返工这是整个配置环节里我觉得最值得花时间的一件事因为一旦前期处理不当等你写了上百篇带图的文档再想调整返工量是灾难级的。Markdown 引用图片写的是路径路径分两种绝对路径和相对路径。绝对路径长这样C:/Users/xxx/Pictures/a.png看着没问题但只要文件一移动、换台电脑、发给了别人图全部裂掉。相对路径则是./assets/a.png只要图片跟着文档目录一起走到哪儿都能显示。Typora 有一个专门针对这个问题的功能在偏好设置的“图像”面板里可以设置插入图片时自动复制到指定目录通常设成./assets或者./${filename}.assets这种形式。这样你从剪贴板粘贴一张截图它会自动存到文档旁边的资源文件夹路径自动写成相对路径全程不用手动管理。顺手再勾上“优先使用相对路径”。这一步做完你的文档就变成了一个自包含的文件夹一个.md文件加一个同名资源目录拷到任何地方都能正常显示。提示如果不是单篇文档而是一个完整的笔记库可以把所有图片统一收在一个顶层assets目录里再用相对路径跨级引用。好处是去重方便、备份体积小代价是路径里会多几层../看源码时略乱。两种方案都能用关键是整个库内保持一致别一半用这套一半用那套。3. Markdown 语法够用、够稳、不容易忘的那一版3.1 标题、段落与那个绕不开的换行问题标题用井号几个井号就是几级标题最多六级。写法上有个约定俗成的细节井号后面最好加一个空格# 标题而不是#标题。不加空格在某些解析器里识别不出来。一级标题在一篇文档里通常只用一次就是文档标题正文里的结构从二级开始比较舒服。段落之间用空行分隔。这是 Markdown 里最重要的一条规则比任何符号都重要。你连续写几行文字解析器会把它们当成同一段中间渲染成一个空格只有空行才表示段落结束。很多人第一次用 Markdown 都觉得“我明明换行了怎么没换”原因就在这儿。如果确实需要在一个段落内强制换行有几种做法第一行结尾加两个空格 第二行跟在上面两个空格后面 第一行结尾加反斜杠\ 第二行 第一行 br 第二行用 HTML 标签兼容性最好但不够“纯”实测下来行尾两个空格是最通用的写法但它有个隐患很多编辑器会自动删除行尾空格包括某些代码规范检查工具所以协作场景下容易被清掉。\反斜杠更保险一些Typora 和主流解析器都支持。至于br属于兜底方案实在不行再用。我个人的规矩是段落一律用空行分开绝不依赖行尾空格只有在同段落内确实需要断行的场景比如诗歌、地址、代码注释才用反斜杠。3.2 列表、引用、代码块与转义无序列表用-或*开头加空格有序列表用1.开头加空格。嵌套靠缩进通常缩进两个或四个空格。这里建议整个文档统一用四个空格因为不同解析器对两空格的兼容性略有差异四空格最稳。任务列表是很多人不知道但非常好用的功能写法是- [ ] 待办和- [x] 已完成渲染出来是可勾选的方框。用它做需求清单、发布检查表非常顺手比单独列一堆文本直观得多。引用块用大于号开头可以嵌套常用于标注提示和注意事项。代码块用三个反引号包裹强烈建议在开头就写上语言名比如python、javascript、bash。原因有两个一是渲染时会有语法高亮读代码轻松很多二是很多工具包括一些文档站点生成器会读取这个语言标识用来决定怎么处理代码。写代码块时还要注意如果代码透本身包含三个连续反引号要用更长的反引号包围或者改用波浪线~~~。转义是个容易被忽略的点。如果你的正文里本来就需要显示*、#、_这些符号直接写会被解析器吃掉前面加反斜杠即可转义。比如想显示*不是斜体*就写成\*不是斜体\*。中英文混排时_和*特别容易被误伤尤其写变量名如file_name的时候如果两边各有一个下划线中间那段会被识别成斜体。解决办法是用反引号包起来写成行内代码file_name既避免误解析又能在视觉上和正文区分开。3.3 表格手写、对齐与表格互转表格是 Markdown 里手写最费劲的部分没有之一。基础语法是这样| 参数名 | 类型 | 默认值 | 说明 | | :--- | :---: | ---: | :--- | | timeout | number | 3000 | 超时时间毫秒 | | retry | boolean | false | 是否自动重试 | | mode | string | auto | 运行模式 |第二行是分隔行必须存在负责告诉解析器第一行是表头。冒号的位置决定对齐方式冒号在左边是左对齐两边都有是居中在右边是右对齐。这个对齐规则我建议不要省因为同一份文档在不同解析器下的默认对齐策略不一样写死了才稳定。手动写表格效率太低有几个省事的办法Typora 内置表格编辑插入表格后可以用快捷键在单元格之间跳转、插入行列不用手动敲竖线。从 Excel 复制在 Excel 里选中区域复制直接粘贴进 Typora多数情况下能自动转成 Markdown 表格这是我最常用的方式。表格转回 Excel反过来把 Markdown 表格复制进 Excel一般也能识别成表格结构如果不行先导出成 CSV 再打开。注意Markdown 表格不支持单元格合并也不支持单元格内换行除非借助 HTML。真要写复杂表格建议改用 HTML 表格或者干脆放一张图。别跟语法较劲工具不合适就换。表格宽度也是常被吐槽的点。列数一多源码里一行特别长编辑器不折行的话要横向滚动。建议把|之间的内容适当对齐留白源码可读性会好很多。有的格式化工具能自动对齐愿意折腾可以配一个。3.4 链接与图片路径那点事儿链接分两种写法[行内链接](https://example.com 鼠标悬停提示) [引用式链接][id] [id]: https://example.com 可选标题引用式链接适合同一地址在文内多处出现的情况改地址只需要改一处。写长文档时我基本都用引用式维护成本低。图片语法只比链接多一个感叹号方括号里的替代文字不能省。它的作用有三个图片加载失败时显示这段文字屏幕阅读器会读出来搜索引擎会作为索引依据。很多人图省事写这在无障碍和可访问性上是不合格的。图片大小控制在标准 Markdown 里没法直接设置要缩放得用 HTML 的img标签写 width 属性或者在 Typora 里用它自己支持的扩展语法。跨平台发布的话用 HTML 标签兼容性最好。3.5 数学公式与结构化图表Typora 对数学公式的支持是它能拿下技术写作人群的关键原因之一。行内公式用单个美元符号包裹块级公式用两个美元符号包裹并独占一行质能方程 $E mc^2$ 写在行内。 $$ \sum_{i1}^{n} i \frac{n(n1)}{2} $$块级公式可以多行书写也支持对齐环境。导出 PDF 时公式一般能正常渲染成矢量图形导出到某些不支持公式的平台则会退化这点后面工作流那一节会细说。至于流程图、时序图这类结构化图表Typora 内置了对相关文本描述语法的渲染支持写出来直接变成图。它的价值在于图表和文字放在同一个文件里改需求时图跟着改不会出现图文档不一致的情况。这块值得单独花时间研究我这里只提醒一点这类语法的渲染依赖解析器支持不是所有 Markdown 平台都能渲染出来往外发布前先确认目标平台是否兼容。4. 把 Typora 接进已有的工作流4.1 与代码编辑器、笔记本的分工Typora 不是万能的也没必要什么都用它。我的分工是这样Typora写正式文档、长文、方案、笔记需要长时间专注写作的场景。VS Code在项目仓库里改 README、写代码注释、需要同时看多个文件时。装 Markdown 插件后编辑体验也不差而且和代码在同一个窗口上下文切换成本低。Jupyter Notebook跑数据、做分析、需要代码和输出结果穿插呈现时。Notebook 的单元格本质上也是 Markdown写完的说明可以直接搬到 Typora 里。三个工具之间切换靠的就是.md这个通用格式。VS Code 里写的文档Typora 打开完全一致Typora 里写的说明段复制进 Jupyter 单元格也直接生效。这也是我前面反复强调“语法该学”的原因——格式通用才是效率的根源。4.2 导出Markdown 转 Word、PDF、HTMLTypora 的导出功能是它的隐藏实力。菜单里能导出 PDF、HTML、Word、EPUB、LaTeX、图片等多种格式。导出 Word 需要额外装 Pandoc这是个文档格式转换工具装完之后 Typora 会自动识别。导出时可以用默认模板也可以指定自定义的.docx参考模板——做法是先导出一份默认的在 Word 里把样式标题字体、正文字号、页边距改成你要的样子再作为模板导回去。这样每次导出都是统一格式特别适合需要定期交周报、月报的场景。导出 PDF 有两条路内置导出和走 Pandoc。内置的排版还原度高公式和图都能正常渲染走 Pandoc 的好处是可以配合 LaTeX 模板做更精细的排版代价是配置门槛高。这里有一个实操上的坑要提醒导出前先检查图片路径。如果文档里用了绝对路径的图片导出后发给别人对方打开就是一堆裂图。用相对路径加同目录资源文件夹的方案导出的 PDF 和 HTML 才能带着图走。还有一个常见需求是“转成 HTML 后粘贴到网页编辑器”。这时候注意多数平台会过滤掉一部分内联样式粘过去可能变形。稳妥做法是导出 HTML 后把导出的文件在浏览器里打开全选复制再粘贴到目标编辑器。这样比直接复制 Markdown 源文更保真。4.3 网页剪藏与格式互转写东西的人总在收集资料。常见需求是“看到一篇好文章想存成 Markdown 留着”。浏览器有一类剪藏扩展专门干这个把网页正文提取出来转成 Markdown图片按你的规则下载到本地或者保留外链。这类工具选型时看三点正文提取干不干净能不能自动去掉广告和导航、图片处理方式下载到本地还是保留链接、代码块和表格保留得完不完整。前两点决定可用性第三点决定技术类文章的质量。用过几款之后我的经验是技术博客的代码块是重灾区经常被提取成一堆散掉的文本拿回来还得手动修。另一个方向是各种文档格式往 Markdown 转。PDF 转 Markdown、Word 转 Markdown、HTML 转 Markdown 都有开源工具转换质量参差不齐。PDF 尤其难因为 PDF 本来就不是为“结构化文本”设计的它是为打印设计的表格和公式转出来经常是乱的。我的做法是结构性强的文档Word、HTML才值得自动转PDF 老老实实复制粘贴重排跟工具较劲的时间够你手打两遍了。4.4 笔记库组织与版本管理当文档数量上去之后组织方式是绕不开的问题。我的建议是尽量简单别一上来就搞复杂分类体系。一套我用了两年的目录结构供参考notes/ assets/ # 全局图片资源 inbox/ # 临时收集每周清空 01-docs/ # 正式文档、方案 02-notes/ # 学习笔记、读书笔记 03-snippets/ # 代码片段、常用配置 templates/ # 各种文档模板关键点在于inbox 目录。任何临时想法、剪藏的网页、没想好放哪儿的东西全部先扔进去每周固定时间清理一次归类或删除。没有这个缓冲你的库很快就会变成垃圾场。版本管理方面纯文本最大的优势就是可以直接上 Git。个人用的话本地建个仓库配一个免费托管平台的私有仓库定期 push 就行。好处是改错了一个字能翻回去误删了能恢复换电脑直接 clone 下来。用 Git 管笔记不需要懂复杂的分支操作掌握add、commit、push、log这四个命令基本够终身受用。5. 常见问题与排查实录5.1 排版类问题速查下面这张表是我在群里被问得最多的排版问题直接对照解决现象原因解决办法换行不生效两行黏在一起段间没空行段落之间加空行星号被吞掉没有加粗前后缺少空格或成对缺失确保**文字**两侧有空格变量名下划线变成斜体_被识别为强调标记用反引号包成行内代码表格渲染不出来缺分隔行或列数不匹配补上 井号标题没生效井号后缺空格改成# 标题列表嵌套错乱缩进不统一全文统一用四个空格缩进代码块里的内容被解析没用围栏包裹用三个反引号包裹并标注语言这类问题的共同点是几乎全部源于“符号和文字之间的空格”以及“空行”。Markdown 的解析器对空格很敏感写的时候养成“符号后面跟一个空格”的习惯能避免八成以上的排版问题。5.2 图片与路径类问题排查图片不显示是所有 Markdown 使用者都会遇到的坎排查顺序建议固定下来看路径类型。源码里是C:/...还是./...前者是绝对路径换环境必挂优先怀疑。看大小写。Linux 和部分服务器环境对文件名大小写敏感Image.png和image.png是两个文件。看是否带中文或空格。路径里只要有这两样某些工具链就会出问题建议统一改成英文加连字符。看图片是否真的存在。有时候是粘贴时没成功写入资源目录里根本没有这个文件。看导出目标。在编辑器里能显示导出后没了问题多半出在导出流程没把资源一起打包。我踩过最典型的一次坑用手机同步备份资料时只同步了.md文件忘了同步assets目录结果在新设备上全部显示裂图。从那以后我的规矩是文档和资源目录必须一起拷贝、一起备份永不分离。5.3 导出与字体类问题导出 PDF 时偶尔会遇到中文变成方框或者乱码这通常不是 Markdown 的问题而是导出工具用的字体里没有中文字形。排查思路分两步先确认系统里装了完整的中文字体集再检查导出配置里指定的字体名是否正确。走 Pandoc 导出的话可以在配置里显式指定中文字体。导出 Word 时如果样式混乱八成是没做参考模板。默认导出的样式比较朴素标题层级和正文没有明显区分。花二十分钟做一份自己的.docx模板能省下以后每次导出后的手动调格式时间。还有一个容易被忽略的点导出的文件体积。如果文档里嵌了大量高分辨率截图导出的 PDF 可能几十兆邮件都发不出去。养成习惯截图后用压缩工具过一遍或者截图时就把分辨率调低屏幕上看的文档 1000px 宽度足够了。5.4 我踩过的几个坑和几条私房经验最后这部分是我自己攒下来的文档里通常不写但用起来很实在。**第一条备份永远比技巧重要。**不管你用了多优雅的工作流只要没有备份一次误删就能让你损失半年的积累。我的方案是三层本地目录定期整包压缩、云端同步一份、Git 仓库一份。三层里任意两层同时挂掉才会真丢东西这个概率已经足够低了。**第二条别过早追求完美的工作流。**我见过太多人花两周研究目录结构和标签体系结果一篇笔记都没写。正确的顺序是先用最简陋的方式记起来记录量上来之后再根据实际痛点去优化结构。信息量不够的时候任何分类体系都是拍脑袋。**第三条模板比快捷键更省时间。**建几个常用模板——会议记录、周报、技术方案、读书笔记——每写一份新文档就复制一份模板改。比每次从空白页开始构思结构要快得多而且能保证同类文档格式统一。**第四条定期做一次“断舍离”。**每季度翻一遍自己的笔记库删掉过期内容、合并重复文档、把临时笔记整理成正式文档。这个过程一开始会心疼但你会发现自己真正有用的东西其实就那么几十篇剩下的都是噪音。库越干净检索越快用起来的意愿也越强。**第五条把长文拆成短文件。**一篇两万字的大文档打开慢、改起来提心吊胆、Git 冲突时几乎没法处理。我的做法是单个文件控制在三千字以内用目录索引文件把相关文档串起来。这样每个文件都能独立维护改动影响面小找内容也更快。说到底工具终究只是工具。Typora 也好别的编辑器也好它们解决的都只是“让写作这件事少一点摩擦”。真正决定产出质量的还是你脑子里有没有东西以及愿不愿意把它写清楚。我用了这么久最大的感受是一个好工具能让你愿意多写而多写本身才是唯一能把写作这件事变好的路径。
