我第一次真正对 Markdown 写作产生兴趣是因为一次特别狼狈的改稿。对方发来一份排版精美的文档我小心翼翼地改了几段话发回去结果对方打开后说排版全乱了标题字号变了行距挤在一起几个加粗的地方也消失了。那天我花了半小时跟格式搏斗真正改内容只用了五分钟。后来在另一个协作场景里有人直接丢给我一个后缀是 .md 的纯文本文件说“你随便改改完发回来就行”。我将信将疑地打开满屏的井号和星号第一反应是这东西也太原始了。可当我改完发回去对方那边渲染出来的文档结构清清楚楚一个标点都没跑偏。从那次起我开始认真对待 Markdown 写作这件事。这篇内容写给和我当初一样的新手如果你平时要写笔记、整理资料、写稿子、做文档又不希望自己被某个软件的排版规则牵着走那这套东西值得花一个小时学明白。它不难难的是很多人一开始就被“语法”两个字吓退了。1. 一份被改乱的文档让我彻底倒向纯文本很多人以为文档出问题是因为自己操作不当其实不是。问题的根源在于富文本格式把“内容”和“长相”焊死在了一起。你在文档里敲一个标题软件记下的不只是“这是一段标题文字”还记下了“字号 22 磅、颜色深蓝、段前间距 12 磅、字体是某个特定字库”。这些信息跟着文字一起走一旦换台机器、换个版本、缺个字体它就得重新找补找补的结果就是排版跑偏。1.1 富文本的本质把样式和内容打包成一个整体用生活里的场景类比就很清楚。富文本像是一盘已经摆好盘的菜菜、盘子、摆盘的花纹全焊在一起端上来。你想把菜拨到另一个盘子里花纹就跟着碎。Markdown 更像是一张写着“这是一道凉菜、主料是黄瓜、口味偏酸”的菜谱卡片谁拿到卡片都能按自己的盘子重新摆一遍摆出来样子可能不同但内容和结构一分不差。从技术上看常见的富文本文档本质上是一个压缩包里面装着若干描述页面结构的标记文件再挂上字体、图片、样式表。你看到的“一段话”在文件内部是几十行结构描述。这些描述之间互相引用复制粘贴的时候如果只带走一部分引用就断了样式自然崩。这也是为什么从网页复制一段文字到文档里常常带着一堆莫名其妙的字号和颜色。1.2 Markdown 只回答“这是什么”不回答“长什么样”这是理解 Markdown 最关键的一句话。你在文字前面敲一个井号表达的是“这是一个一级标题”而不是“请把这段字放大到 24 磅并加粗”。至于这个一级标题最后是 24 磅还是 28 磅、是黑体还是宋体、是深灰还是纯黑完全由渲染它的那套样式决定。这个分离带来的直接好处是同一份源文件在屏幕上看是一种样子打印出来是另一种样子导出成网页又是第三种样子但三种样子里的标题层级、段落归属、列表结构完全一致。你写一次适配多个出口。反过来如果你在富文本里手工调了三套排版改一个字都可能要重新对一遍三处格式。我在实际使用中最大的感受是“心智负担变小了”。写作的时候我不再关心字号和缩进只需要判断这句话是正文还是小标题、这个条目属于列表还是独立段落。判断完敲两个符号继续往下写。所有的视觉决策被推迟到最后一刻由一套统一的样式一次性处理掉。1.3 纯文本的寿命比你正在用的软件长得多这一条对新手来说最容易被忽略但它恰恰是最值钱的。Markdown 源文件就是一个普通的纯文本文件用记事本打开也能看二十年前的机器能读二十年后的机器大概率也能读。它不依赖某个特定软件的数据库不需要登录不需要联网同步不会因为软件停止维护就变成一堆打不开的乱码。我见过太多人把几年的笔记、稿件全放在某个专用格式里换设备的时候才发现导出功能残缺图片全丢层级全平。而纯文本文件的好处是你随时可以换工具工具换了一圈文件还是那些文件一个字节都不少。这个特性对长期写作的人来说价值远超任何花哨的功能。提示判断一个写作工具值不值得长期投入先看它能不能把内容原样导出成纯文本或 Markdown。如果导出后结构丢失那你写的每一个字都在给别人交押金。2. 真正每天用到的语法其实只有十来个符号新手最容易犯的错是把 Markdown 当成一门要系统学习的语言去找几十页的语法手册从头背。实际上你日常写作百分之九十的场景用到的标记不超过十二个。剩下的那些遇到再查完全来得及。2.1 先把“块”和“行内”两个层级分开看Markdown 的标记可以分成两类理解了这个分类语法表就不用死记了。一类是块级标记它作用于“一整块内容”标志是通常要独占一行而且前后往往需要空行来分隔。标题、段落、无序列表、有序列表、引用块、代码块、分割线、表格都属于块级。块级标记管的是文档的骨架。另一类是行内标记它作用于“一句话里的某几个字”可以出现在段落中间任意位置。加粗、斜体、行内代码、链接、删除线都属于行内。行内标记管的是局部的强调。分清楚这两类之后你会发现很多“语法没生效”的问题本质是把行内标记写在了需要块级标记的位置或者反过来。比如想让一段话变成引用你在句首敲了一个大于号但前面没有空行渲染器可能把它当成上一段的一部分。这类问题的排查思路后面会细讲。2.2 一份可以直接抄走的最小语法清单下面这张表覆盖了新手写作九成以上的需求建议直接存下来对照用。想要的效果写法关键注意点一级到六级标题行首敲 1 到 6 个#后面跟一个空格井号与文字之间必须有空格否则不识别普通段落直接写段与段之间空一行不空行会被合并成同一段无序列表行首用-或*加空格符号后必须有空格有序列表行首用1.加空格序号不必连续渲染时自动编号引用行首用加空格可以嵌套多个叠加行内代码用反引号把内容包起来适合写文件名、命令、变量名代码块三个反引号独占一行下一行写语言名结尾再用三个反引号闭合加粗内容两侧各两个星号星号要紧贴文字中间不能有空格斜体内容两侧各一个星号中文场景下斜体辨识度低慎用链接方括号写文字圆括号写地址圆括号里不能有空格图片感叹号加方括号加圆括号圆括号里是图片路径或地址分割线单独一行写三个或以上短横线前后要空行把这张表里的十二行练熟你的写作效率就会有一个明显的台阶。我建议新手第一天只练前四行标题、段落、两种列表。这四样能撑起一篇结构完整的笔记其余的在需要的时候查表就行。2.3 语法的“少”是设计时刻意克制的结果很多人第一次看完 Markdown 语法会有一个疑问为什么不能设置字号、颜色、居中、首行缩进答案很直接因为它的设计目标不是“排出一份好看的文档”而是“写出一份连源代码本身都能读懂的文稿”。这个目标决定了它必须克制。如果允许随意设颜色和字号源文件里就会塞满样式描述不渲染的时候根本没法读。而 Markdown 的原始设计里有一条硬性原则即使你把源文件当普通文本从头读到尾它也应该通顺、层次清楚。井号后面的标题一眼能看出是标题短横线开头的条目一眼能看出是列表这个“裸读也清楚”的特性才是它真正的价值所在。理解了这层克制你就不会抱怨它功能少反而会明白需要精排的时候应该交给样式表或者导出工具去处理而不是在源文件里手工堆样式。3. 新手最先卡住的几个地方以及我是怎么绕过去的语法本身十分钟能看完真正让人抓狂的是那些“明明按教程写了却没反应”的时刻。下面这几个坑我全踩过有些还反复踩把排查过程写出来你遇到时能少绕几圈。3.1 换行不生效一个空行决定了一切这是新手遇到的第一个坎几乎百分之百会撞上。你在源文件里敲了回车把一句话分成两行渲染出来却发现两行被粘成了一段。原因在于 Markdown 把“单个换行”视为软换行等同于一个空格。这在英文排版里是合理的因为英文段落内部的换行只是源文件的排版需要不影响语义。想要真正换行有两条路一是在行尾敲两个空格再回车这叫硬换行二是在两行之间插入一个空行让它们变成两个独立段落。我自己的习惯是只用第二种。行尾两个空格在编辑器里看不见很容易被自动格式化工具清掉或者复制粘贴时丢失排查起来极其费劲。干脆统一用空行分段规矩简单不会出错。代价是段落之间视觉上会多出一些空白但这个代价完全可以接受。排查链路是这样的发现两行粘在一起先看中间有没有空行有空行还粘检查是不是在列表项内部列表项内部的换行规则不一样最后再检查编辑器有没有开启“保存时自动清理行尾空格”这个功能会悄悄干掉你的硬换行。3.2 列表和代码块会“吃掉”后面的内容这个坑比换行隐蔽得多。你写了一个列表列表最后一项下面想接一段普通正文结果这段正文被渲染成了列表的一部分前面多出一个小圆点缩进也不对。或者你在列表项里嵌了一个代码块代码块之后的所有内容都变成了代码。根本原因是缩进层级。Markdown 判断一段内容属于谁靠的是缩进量。列表项的内容需要和列表标记之后的第一行文字对齐通常是两个到四个空格。如果你想在列表项内部放一个代码块代码块还要再额外缩进具体是四个空格还是八个取决于你用的渲染器遵循哪套规范。这一点各家实现确实存在差异是 Markdown 最不统一的地方之一。我的处理办法是尽量不在列表项内部塞代码块需要放代码就把列表拆开代码块单独成段前后各留一个空行。这样牺牲了一点紧凑感换来的是稳定。如果非要嵌套就把整个文件丢进一个支持实时预览的编辑器边改边看缩进对不对比盲改快得多。3.3 中文环境下的全角符号是最容易被忽略的元凶这个问题很少被教程提到但在中文写作里出现频率极高。你从某个中文网页复制了一段带格式的文字或者手滑把输入法切到全角敲出来的星号、井号、方括号全是全角字符。它们肉眼看上去和半角几乎一样渲染器却完全不认。我自己就干过这种事一段加粗怎么都不生效反复检查语法最后放大字体才发现那两个星号是全角的宽度比正常星号多了一点。从那以后我养成了一个习惯凡是标记符号没生效第一步先把符号删掉切换到半角输入法重新敲一遍。还有一个相关的细节中文字符和星号之间不要留空格。英文习惯在标记和文字之间加空格中文里加了空格有时会导致加粗范围判断出错尤其是加粗内容以中文标点开头或结尾的时候。稳妥的写法是星号紧贴文字中间不留任何空白。3.4 表格里的竖线冲突与对齐行表格是新手最容易写崩的块级元素。它的结构要求比较死第一行是表头第二行必须是一行由短横线和竖线组成的分隔行第三行开始才是数据。少了分隔行整张表就退化成普通段落。分隔行里还可以用冒号控制对齐冒号在左边是左对齐在两边是居中在右边是右对齐。这个细节很多人不知道写出来的表格全是默认对齐。更常见的坑是单元格内容里本身含有竖线比如写一个命令行参数或者一段正则表达式。这时候竖线会被当成列分隔符把一格切成两格整张表瞬间错位。解决办法是在竖线前面加一个反斜杠转义。这个转义规则同样适用于星号、下划线、反引号这类有特殊含义的符号凡是你不希望它被当成标记的字符前面加反斜杠基本都能解决。4. 我写一篇东西的完整流程从空白文件到能发出去的稿子语法会了之后下一个问题是“怎么用”。很多人学完语法还是写不出结构清楚的长文不是因为不会敲符号而是因为没有形成流程。下面这套流程是我改了十几遍之后稳定下来的写笔记、写方案、写长文都用它。4.1 第一步永远是搭骨架标题层级就是大纲打开一个空白文件我做的第一件事不是写正文而是把所有标题敲出来。一级标题是文章名二级标题是主要章节三级标题是章节内的子点。敲完之后通读一遍标题如果读下来逻辑是通的这篇文章基本就成了如果标题之间跳跃、重复、层次混乱那正文写得再漂亮也救不回来。这里有一条我自己的硬规矩标题层级最多到三级。一旦发现需要写四级标题说明这一块内容太杂应该拆成两个二级章节或者把其中一个子点提升为独立章节。四级以上的标题在阅读时几乎失去了导航作用读者扫一眼目录根本记不住那么细的层级。还有一个细节标题的井号和文字之间那个空格千万不能省。我见过不少人写成井号紧贴文字本地编辑器可能宽容地渲染出来了换个平台就变成普通段落整篇文章的目录全废。4.2 填正文阶段一段只讲一件事骨架搭好之后开始填内容。这个阶段我给自己定了一条规则一个段落只讲一个意思段落的第一句话就是这个意思的结论。后面几句是解释、举例或者补充条件。这样写出来的段落读者扫每段第一句就能抓住全文脉络也方便自己回头检查有没有跑题。段落的长度我一般控制在三到六行折算成字数大概一百五到三百字。太短了信息密度不够读起来像在蹦字太长了读者容易走神尤其在手机上。这个尺度不是硬标准但作为默认值很好用。写的过程中我尽量不回头改。初稿阶段追求的是把想法倒干净标点、措辞、案例顺序全部留到第二遍处理。很多人写不下去就是因为一边写一边纠结用词写三行删两行半小时过去还在开头。先把东西写出来哪怕粗糙改起来永远比从零写要快。4.3 收尾阶段统一处理链接、图片和交叉引用正文写完之后我会专门过一遍所有外部资源。链接检查两件事地址里有没有空格文字描述是不是能独立看懂。图片检查三件事路径是相对路径还是绝对路径文件名有没有中文和空格图片尺寸会不会撑破版面。图片路径这块我要多说一句。如果你打算把源文件和图片一起打包发给别人或者传到某个协作空间一定要用相对路径而且图片最好放在和源文件同级的固定目录里。绝对路径在你自己的机器上能用换台机器立刻全部裂图。文件名也别用中文和空格虽然现在大部分工具都支持但跨平台传输时出问题的概率明显更高改成英文加短横线最稳。4.4 导出这一步想清楚你到底要什么Markdown 源文件适合存档和继续编辑不适合直接发给不看源文件的人。所以最后一环是导出。导出成网页适合在线阅读导出成便携文档格式适合打印和正式交付导出成图片适合发在即时通讯里。导出过程一定有损耗这点要有心理准备。表格在窄页面上可能被压缩长代码块可能被截断中文字体在某些转换链路里会回退成默认字体。我的做法是导出之后一定从头翻一遍重点看表格、代码块和图片这三类元素。如果某份稿子要正式交付我会在导出后手工微调那几处而不是反复折腾源文件去迁就导出效果。源文件保持干净导出物单独处理这个分工要守住。5. 工具的三条路线本地编辑器、笔记库、代码编辑器工具选择是新手最容易纠结的部分市面上的选择确实多。我把它们归成三条路线你对着自己的需求挑就行不用把它当成一道难题。5.1 双栏实时预览型上手最快适合纯写作这类工具打开就是左边写、右边看语法高亮、目录生成、导出功能都现成。对新手最友好的一点是反馈即时你敲完一个标记立刻能看到效果学习成本极低。它们的定位是“写作工具”所以界面干净干扰少适合写稿、写笔记、写文档这类以文字为主的工作。局限在于扩展性。它们通常不支持插件不方便做批量处理也很难和版本管理、自动化流程对接。如果你的需求就是安安静静写东西这些局限不影响你如果你想把写作嵌进一套更大的工作流就得考虑另外两条路线。5.2 知识库型靠组织方式取胜但要留意格式私货这类工具的核心卖点是笔记之间的关联和检索适合长期积累、需要反复回看的场景。它们的编辑区通常也支持 Markdown写起来和上一类差别不大。需要警惕的是“格式私货”。有些工具会在标准语法之外增加自己的扩展标记比如特殊的引用块、特殊的任务列表、特殊的嵌入语法。这些扩展在它自己的环境里很好用一旦你把文件导出到别处这些标记要么失效要么变成一堆看不懂的符号。选这类工具之前我建议先做一次导出测试随便写一篇带标题、列表、表格、代码块的笔记导出成纯文本看看结构还在不在。这个测试花不了五分钟能帮你避开后面几年的迁移麻烦。5.3 代码编辑器型自由度高门槛也高第三条路线是用通用的代码编辑器加插件来写 Markdown。好处是极其自由语法高亮、实时预览、拼写检查、表格格式化、图片粘贴上传缺什么装什么而且它天然和版本管理、批量脚本、命令行工具配合得很好。代价是配置成本。你得自己挑插件自己调快捷键自己解决插件之间的冲突。对完全没有技术背景的人来说光是装插件这一步就可能劝退。我的建议是如果你已经有常用的代码编辑器顺手装两个 Markdown 插件就行不必为写作专门折腾如果你从来没用过这类工具别从这条路线入门。路线上手成本扩展能力导出可控性适合的人双栏实时预览型低装完就能写弱基本靠内置功能中等够用但不精细以写稿、写笔记为主知识库型中等要理解它的组织逻辑中等靠内置扩展需要先做导出测试长期积累、频繁检索代码编辑器型高要会配插件强几乎不受限高可接自动化流程已有技术工具使用习惯5.4 我的选择逻辑先看十年后还能不能打开功能对比看完真正让我下定决心的其实是一个很朴素的问题十年后这份文件还能不能打开按这个标准筛答案很明确源文件必须是本地存放的纯文本文件名和目录结构由我自己控制工具只是打开它的一个入口换掉工具不影响文件本身。所以我的做法是文件全部放在本地固定的目录里用简单的层级分类编辑工具换过好几轮文件一次都没迁移过。顺带说一个实际经验不要把所有东西都塞进一个巨大的文件。单文件超过几千行之后编辑器会变慢定位变难改一处要滚动半天。我一般按主题拆成多个文件再用一个索引文件把它们的链接串起来。这样既保持了单文件的轻量又能从索引页跳到任意一篇。6. 把 Markdown 用成长期资产几个让我受益的习惯语法和工具都是表层的东西真正拉开差距的是习惯。下面这几条不是什么高深技巧但坚持下来之后我回头找东西的效率提高了不止一倍。6.1 文件命名和目录结构比编辑器重要得多我见过太多人的笔记目录是这样的新建文件夹、新建文件夹(2)、未命名文档、最终版、最终版真的最终版。这种结构用三个月就找不回东西了。我的规矩有三条。第一文件名带日期前缀格式统一这样按名称排序就是时间顺序。第二目录层级不超过三层超过三层说明分类逻辑有问题应该用文件名里的关键词来区分而不是继续建文件夹。第三同一类内容用一个固定的命名模式比如主题加日期加版本标记看一眼文件名就知道是什么、什么时候写的、是不是最新。这三条听起来很琐碎但它们决定了你半年后还能不能在这堆文件里精准捞出一篇需要的内容。工具会换习惯不会。6.2 用模板消灭重复劳动如果你发现自己每次写同类文档都在重复敲同一批结构那就该做模板了。模板可以简单到一个空文件里面预置好标题层级、常用的几个小节、固定的表格骨架。新建的时候复制一份改个名字就能往里填。更进一步的做法是在文件开头写一段结构化的元信息用三个短横线包起来里面写标题、日期、标签、状态这类字段。这段东西严格说不是标准 Markdown 语法但被大量工具支持用来做检索和归档非常方便。字段名用英文值用中文这个组合在大多数场景下都不会出问题。注意元信息区块必须放在文件最开头前面不能有任何空行或文字否则会被当成普通段落渲染出来既不美观也影响检索。6.3 版本管理不一定要上重型工具很多人一听版本管理就想到复杂的命令行工具其实对个人写作来说有更轻的做法。最轻的做法是日期后缀。每次大改之前把当前文件复制一份在文件名后面加上当天的日期。优点是零成本、零学习曲线缺点是文件会越堆越多需要定期清理。中等强度的做法是用云盘的历史版本功能改坏了直接回滚到某个时间点不用自己管副本。最重的做法才是用专业的版本管理工具适合需要多人协作、需要精确对比每次改动的场景。方式学习成本能回滚到多久之前适合场景日期后缀副本几乎为零取决于你留了多少份个人写作改动不频繁云盘历史版本低通常有固定保留期个人写作希望自动备份专业版本管理高完整历史可精确对比协作、长期维护的文档库我自己的组合是云盘自动备份加关键节点手动留副本。日常小改靠自动备份兜底大改之前手动存一份两条线并行心里踏实。6.4 把高频片段做成可复用的块写了一段时间之后你会发现有些内容反复出现常用的表格骨架、固定的检查清单、某几段说明文字、常引用的几条规范。这些东西每次重敲一遍纯属浪费。我的做法是建一个片段文件把这些高频内容分类存好需要的时候复制粘贴改掉具体内容就行。更进一步如果某些片段需要频繁插入可以了解你所用编辑器有没有“自定义模板”或者“代码片段”的功能设置一个短缩写敲缩写加触发键就能展开整段内容。这个功能在各类编辑器里叫法不同但基本都有值得花十分钟配置一下。7. 有些活儿真的别用 Markdown 干说了这么多好处得说点实话。Markdown 不是万能的它在某些场景下会给你添堵。新手最容易犯的错是学了一个工具就想拿它解决所有问题。下面这几类活儿我试过结论是不划算。7.1 需要精确控制版式的文档合同、正式函件、需要严格按模板排版的材料这类东西的核心诉求就是“每一页长什么样必须完全可控”。行距多少、页边距多少、某个签字栏必须落在第几页的什么位置这些要求 Markdown 天生做不了它的设计哲学就是不管这些。硬要用也行靠导出工具加自定义样式表能凑出个大概。但你会花大量时间在调样式上而且每次内容变动都可能导致分页位置改变之前调好的又得重来。这种活儿老老实实用擅长排版的工具把精力留给内容本身。7.2 多人同时改同一份稿子Markdown 是纯文本理论上可以用版本管理工具做合并但那是给有技术背景的人准备的。对普通协作场景来说两个人同时改同一个文件冲突处理和合并的体验相当糟糕。你不知道对方改了哪几行工具也没法像富文本那样直观地显示修订痕迹。我的做法是分工拆分不同章节拆成不同文件各写各的最后由一个人统一汇总。汇总时只做拼接和统一术语不做内容改写。这个流程比多人共编一个文件稳得多。7.3 图表密集、公式密集、需要复杂交互的场合大量流程图、复杂嵌套表格、需要交互操作的演示材料这些都不是 Markdown 的强项。表格这块尤其明显标准语法不支持合并单元格稍微复杂一点的表格就得靠内嵌网页标签来凑可读性立刻崩掉。数学公式倒是有解很多渲染器支持在特定符号之间写公式语法写出来的效果不错。但这依赖渲染环境换个不支持的地方就是一堆原始符号。如果一篇内容公式占比很高又需要到处分发那就得先确认接收方能不能正常渲染不能的话还是换格式。说到底工具的价值在于匹配场景。Markdown 擅长的是结构清晰、以文字为主、需要长期维护和反复修改的内容。认清这条边界你就不会在它不擅长的地方跟它较劲也不会在它擅长的地方白白浪费力气。我现在的状态是日常九成的写作都在 Markdown 里完成遇到需要精排的交付物再导出处理遇到必须协作修订的稿子就切回大家都能用的格式。这套分工用了几年没出过什么大问题。如果你刚开始别急着一步到位先把标题、段落、列表这三样用熟写满十篇东西剩下的自然就顺了。
