Markdown入门：纯文本写作与版本管理实践

1. 我为什么把日常写作工具换成了 Markdown

先说结论：如果你有大量文字需要写、需要改、需要长期存放，并且希望十年后打开还认得出来，那 Markdown 值得你花半小时学一下。这篇就是写给完全没接触过的人看的，不预设任何编程基础。

我自己的转折点很朴素。前几年做项目文档，一份几十页的稿子，前后改了十几版。每次改完，文件名后面就多一个后缀，从“终稿”到“终稿2”再到“真的终稿”，最后自己也分不清哪份是最新的。更麻烦的是格式：一级标题的字号、行距、段前段后间距，全靠鼠标一个个点，某一版不小心把正文样式刷到了标题上，全文几十处标题全废，只能一行一行往回修。那天晚上我坐在屏幕前，突然意识到一件事：我花在“调格式”上的时间，可能比我花在“写内容”上的时间还多。

后来换成 Markdown，同样的文档，改版只是改几行文字，格式自动跟着走。文件从几百KB的文档缩到几KB的纯文本，丢进任何一台设备都能打开，邮件附件发出去对方也不用装特定软件。最直观的变化是：我终于可以把注意力全部放在“这句话该怎么写”上，而不是“这个字号该调成几号”。

Markdown 这个词听起来像技术圈的暗号，其实拆开看特别简单：它是一种用普通字符标记排版的书写方式。标题前面加个井号，列表前面加个减号，加粗用两个星号把字夹住。你写的是纯文本，但任何支持它的地方都能把这几百个符号“翻译”成漂亮的网页、PDF 或者文档。它解决的问题不是“让你写得更快”，而是让内容和样式分开，让文字回归文字本身。适合谁？写技术文档的、写公众号的、做笔记的、写论文草稿的、整理会议纪要的，甚至只是想在手机和电脑之间同步一份待办清单的人——都能用上。

2. 核心原理拆解：纯文本为什么更可靠

2.1 文件本体只是字符，没有任何隐藏结构

理解 Markdown 的第一步，是理解它的文件里到底装了什么。你用记事本打开一个.md文件，看到的和你在编辑器里看到的字符是一样的，没有压缩包、没有二进制块、没有藏在文件末尾的样式表。文件里就是一个接一个的字符，换行就是换行，空格就是空格。

这个特性带来一个很实际的好处：任何能读文本的工具都能读它。手机备忘录、服务器终端、浏览器地址栏、老旧的文本编辑器、甚至某些路由器的配置界面，都能打开。你不需要担心“这个版本的软件打不开那个版本的文件”。我手上有一批十来年前写的笔记文件，当时用的编辑器早就没人维护了，但文件本身照样能打开，内容一个字没少。

对比一下常见的富文本格式：那种格式的文件本质是个压缩包，里面装着正文、样式表、字体引用、修订记录一堆东西。文件一旦损坏，往往整份打不开；换个软件打开，排版可能全乱。它不是不好，只是它的复杂度是为“所见即所得”服务的，而你如果只是写点字，并不需要为这份复杂度买单。

2.2 内容与样式分离，才是省时间的关键

Markdown 的第二个核心思路，是把“这是什么”和“这长什么样”拆开。你只负责声明结构：这一行是标题、这一段是引用、这一串是代码。至于标题用多大字号、什么颜色、什么字体，交给渲染它的人去决定。

这个思路的价值，在你需要“一份内容、多处使用”的时候会特别明显。同一份 Markdown 源文件，投到不同的地方，可以得到完全不同的外观：在文档站上是带侧边栏的网页，在笔记软件里是卡片视图，导出成 PDF 是打印排版，贴到某些平台会自动转成它们自己的格式。你只维护一份源文件，样式由各个出口自己负责。

我做过一个对比，同样一份两千字的产品说明，用富文本方式维护三个版本（网页版、打印版、内部文档版），每次内容更新要改三遍，还容易漏。换成 Markdown 之后，改一遍源文件，三个出口重新导出即可。省下来的不是打字时间，是同步成本和出错概率。

2.3 天然适配版本管理，改了什么一目了然

纯文本还有一个隐藏优势：它特别适合做“差异对比”。因为文件就是一行行字符，任何版本管理工具都能精确告诉你“第三段删了两个字、第五段加了一句话”。而富文本格式的差异对比，往往会得到一堆看不懂的二进制变化，你只能靠人工肉眼找。

这对写长文的人意义很大。一份写了两周的稿子，中间改过几十次，哪天想回退到“上周三那一版”，用版本管理工具几秒钟就能找回来，还能看到当时具体改了哪几句。我个人习惯是每完成一个阶段性版本就提交一次，写一句简短的说明，比如“补充了第三节的参数说明”。半年后回头看，整个思路的演进过程清清楚楚。

注意：不要指望编辑器自带的“撤销”来兜底。撤销只在当前会话有效，关掉软件就没了。真正靠得住的，是文件层面的历史记录。

3. 十分钟上手：真正需要记住的语法就这么几个

3.1 标题、段落与换行的三条硬规则

标题用井号开头，几个井号就是几级标题。这里有个很多人第一次会踩的坑：井号后面必须跟一个空格，否则某些解析器不认。另外一级标题一般一份文档只用一次，用作总标题；正文里的分节从二级标题开始，层级不要跳，别从二级直接跳到四级。

# 一级标题（一般一份文档只用一个） ## 二级标题 ### 三级标题

段落之间要空一行。这一点跟很多人的直觉相反：在 Markdown 里，你在源码里敲一次回车，渲染出来往往还是同一段；只有空出一整行，才会被识别成新段落。刚上手时经常出现“我明明换行了，怎么显示成一整段”，原因就在这里。

至于段内强制换行，有的解析器支持在行尾加两个空格，有的支持反斜杠。我一般不建议依赖这个特性，因为不同平台处理方式不一致，跨平台时容易翻车。需要换行就老老实实空一行开新段落，这是最稳的做法。

3.2 强调、列表、引用、代码这四类最常用

加粗用两个星号夹住，斜体用一个星号。这里提醒一句：中文排版里，成段加粗会让页面很吵，我一般只加粗关键术语和结论句，一段里最多一两处。

无序列表用减号或星号开头，有序列表用数字加点。列表项之间如果要放空行、或者要嵌套子列表，缩进要统一，通常用两个或四个空格。嵌套列表是新手最容易出错的地方，后面第六节会专门讲。

引用块用大于号开头，适合放提示、注意事项、原文摘录。代码行内用反引号包住，多行代码块用三个反引号围起来，并在开头标注语言名，这样渲染出来会带语法高亮。

```python def hello(): print("hello markdown") ```

代码块这个语法值得单独说：它不只用于编程。你把任何需要“原样呈现、不要自动转换”的内容放进代码块，比如目录树、配置片段、命令示例，都能保住原来的空格和对齐。写技术文档的人几乎离不开它。

3.3 链接、图片、表格与分割线

链接写法是方括号包文字、圆括号包地址。图片在前面加一个感叹号。这里有个细节：方括号里的文字是“替代文本”，图片加载失败时会显示它，对无障碍阅读也有意义，别随便写个“图片1”就完事。

表格用竖线分隔列，第二行用减号和冒号控制对齐。冒号在左边是左对齐，两边都有是居中，在右边是右对齐。表格的源码可读性比较差，列一多就难维护，我的经验是超过五列就别用表格了，改成小标题加列表反而更清楚。

分割线用三个减号单独占一行。它的作用是视觉分隔，但滥用会让文章显得碎，我一般只在章节之间的大转换处用一次。

3.4 一份可以直接抄走的语法速查表

这张表里的十来条，覆盖了日常写作九成以上的需求。剩下的扩展语法，比如任务列表、删除线、脚注，用到了再查，完全没必要一次背完。

4. 工具链怎么选：别在选编辑器上耗掉热情

4.1 三类编辑器，按你的使用场景挑

市面上的 Markdown 工具大致分三类，选错类型会让人用得很别扭。

第一类是纯文本编辑器加预览。左边写源码，右边实时看效果，或者按一下快捷键切换。优点是轻、快、不占资源，适合写短文档和快速记录。缺点是对图片、附件、多文件组织的支持比较原始。

第二类是带知识库管理的笔记工具。这类工具把一堆 Markdown 文件组织成一个可以互相链接的网络，支持双链、标签、全文搜索、图谱视图。适合做长期笔记、读书摘录、项目知识沉淀。代价是它往往有自己的“库”概念，文件放在特定目录里，迁移时要留意。

第三类是专注写作的编辑器。界面干净，主打沉浸式写作，导出格式丰富。适合写长文、写稿子。这类工具有的收费，有的免费，功能差异主要在导出和图片处理上。

我的建议很直白：先别纠结，随便挑一个能实时预览的用一周。等你写到三十篇以上，自然会知道自己缺什么——是缺搜索、缺图片管理、还是缺多端同步。到那时候再换，成本也不高，因为文件本身是纯文本，搬走就行。

4.2 图片处理是最大的一道坎，提前想清楚

几乎所有新手都会在图片上卡一下。原因很简单：Markdown 语法里的图片地址是一个路径，而路径分“本地路径”和“网络地址”两种。用本地路径，文件发给别人，图片全裂；用网络地址，得先有个地方存图。

常见的三种做法，各有取舍：

• 本地相对路径：图片和文档放在同一个文件夹（或子文件夹）里，写法是![](images/a.png)。优点是离线可用、不依赖外部服务，整个文件夹打包发出去就是完整的。缺点是文档多了之后，图片文件夹会变得很乱，需要靠命名规范维持秩序。
• 图床（网络存储）：图片上传到某个存储服务，文档里写网络地址。优点是文档本身很轻，随处可看。缺点是多了一步上传操作，而且一旦那个服务出问题，图片就挂了。
• 编辑器内嵌管理：很多笔记类工具会自动把粘贴进来的图片存到指定目录并改写路径。这是最省心的，代价是被这个工具绑得比较深。

提示：不管选哪种方式，文件名不要用中文和空格。用20240312-flow-01.png这种“日期加内容加序号”的命名，跨平台兼容性最好，也方便日后检索。

4.3 导出与发布：一份源文件，多个出口

写完之后的去向，往往决定了你对工具的要求。常见出口有这么几种：

这里有个我踩过的坑：把带表格的文档直接粘到某些聊天工具里，表格会变成一堆竖线加文字的乱码。解决办法是先在编辑器里导出成图片，或者把表格改写成“字段名：值”的列表形式。发布前先在目标平台试贴一小段，比发出去之后再改省事得多。

5. 我的实际写作流程，从空白文件到定稿

5.1 目录结构和命名，决定了你半年后还找不找得到

文件一多，混乱是必然的。我的做法是给每个主题一个文件夹，文件夹里固定几个子目录：drafts放草稿，assets放图片和附件，archive放废弃版本。文件名统一用“日期加主题”，不用“新建文档”“未命名”这种。

notes/ ├── 2024-03-写作方法/ │ ├── drafts/ │ │ └── 20240312-markdown入门.md │ ├── assets/ │ │ └── 20240312-flow-01.png │ └── archive/ └── 2024-04-项目复盘/

这套结构看起来有点啰嗦，但它的价值在于：你不需要记住内容在哪，只需要记住它大概属于哪个主题、大概什么时候写的。靠日期和主题两条线索，基本能在十几秒内定位到任何一份旧稿。

5.2 版本管理其实没那么玄，三条命令够用

如果你完全没接触过版本管理，可以先用最土的办法：每次大改之前，复制一份文件，在文件名后面加日期。这已经比“终稿2”强很多了。

愿意再往前走一步的，可以试试轻量的版本管理工具。日常其实就三条命令：查看当前有哪些改动、把改动记录下来、查看历史记录。记住这三个动作，就够你用好几年。

git status # 看哪些文件改了 git add . && git commit -m "补充第三节参数说明" # 记录这次改动 git log --oneline # 看历史记录

提交说明别写“update”“修改”这种废话，写清楚“改了什么、为什么改”。半年后的你会感谢现在的自己。

5.3 一篇稿子的完整流程记录

我拿最近写的一份说明文档举例，记录一下实际步骤和时间分布。

第一步，搭骨架（约十分钟）。打开新文件，先把所有二级标题敲出来，每个标题下面写一句话概括这段要讲什么。这一步不追求文笔，只求把结构定下来。骨架定完，整篇的篇幅和逻辑顺序心里就有数了。

第二步，填内容（占七成时间）。按标题一段段写，遇到需要举例的地方先写“此处补一个例子”，遇到需要数据的地方先写“待查”，不要停下来查资料。写作和查证分开做，这是我效率提升最明显的一个习惯，因为查资料很容易把人带跑，一小时后回来已经忘了原本要写什么。

第三步，补图和数据（约两成时间）。把之前留的占位补上，图片统一命名放进assets，路径改成相对路径。这一步顺便检查一遍所有链接能不能点开。

第四步，通读和删减（约一成时间）。从头读一遍，重点删三类东西：重复表达同一个意思的句子、为了凑字数加的过渡句、没有信息量的形容词。我通常会把整篇字数砍掉百分之十左右，读起来反而更顺。

第五步，导出和试发布。先导出 PDF 看排版有没有崩，再把内容贴到目标平台预览一遍，确认表格、代码块、图片都正常。

整个流程里，真正“写”的时间其实只占一半多一点，剩下都是结构和检查。但恰恰是后面这些步骤，决定了一份文档能不能被别人看懂、能不能在半年后还被引用。

6. 常见问题与排查实录

6.1 列表缩进错乱，八成是空行和空格的问题

这是最高频的问题。表现是：明明想写子列表，渲染出来却变成了同级；或者列表写到一半突然断掉，后面的内容变成了普通段落。

原因通常有三个。一是列表项之间多敲了空行，有些解析器会把空行当成列表结束的标志。二是缩进用了制表符和空格混排，看起来对齐了，实际字符不一样。三是嵌套层级缩进不够，子项至少要缩进两个空格（有的规范要求四个），缩进量不够就不认。

排查顺序我一般是这样：先把整段列表的缩进全部改成统一的空格（比如都用两个），再看列表项之间有没有多余空行，最后检查列表前后有没有紧贴着其他段落。列表前后各留一个空行，是最不容易出问题的写法。

6.2 表格里的竖线冲突和列宽失控

表格用竖线分隔，那如果单元格内容本身要显示竖线怎么办？答案是转义，在竖线前面加一个反斜杠。不过说实话，出现这种情况就说明这个内容不适合放表格了，改成列表更清楚。

另一个常见问题是列宽。Markdown 源码里的列宽和渲染出来的列宽没关系，你排得再整齐，渲染时也会按内容重新分配。所以不要在源码里花时间对齐竖线，纯属白费功夫。真正影响观感的是单元格内容长度，某列内容特别长的话，整张表会被撑得很宽，手机上直接溢出。我的处理办法是把长内容拆成“字段名加说明”的形式放在表格外面。

6.3 中文排版的两个细节：空格和标点

中文和英文、数字混排时，中间加不加空格？严格来说不是 Markdown 的规范问题，但会影响成品的观感。我的习惯是加：比如“使用 Markdown 写作”“共 12 个文件”。视觉上确实更透气。不过要注意，代码块和链接地址里千万别加，加了就出错。

标点方面，中文内容用中文标点，别混用英文逗号句号。有个隐蔽的坑：某些编辑器会自动把直引号替换成弯引号，代码块里如果出现这个替换，代码直接报错。解决办法是在编辑器设置里关掉“智能引号”，或者写代码时确保它在代码块围栏内部——大部分编辑器在代码块内不会做这个替换。

6.4 一份问题速查表，遇到事先对号入座

注意：排查时优先怀疑“空格”和“空行”。我处理过的格式问题里，超过一半是这两样东西引起的，跟语法本身没关系。

7. 用了几年之后，我最想告诉新手的几件事

第一件，别追求一次写对。Markdown 的语法很少，但排版习惯要养。我刚开始写的时候，经常写完一大段发现层级乱了，然后整段重排。后来学乖了：先把内容全部倒出来，格式最后统一整理。写作状态下不要管格式，改格式是另一个动作，混在一起做，两件事都做不好。

第二件，给自己定一套最小的规范。比如标题最多用到三级、一段不超过五行、列表不超过七项、表格不超过五列。这些数字没什么科学依据，纯粹是经验值，但它们能防止你把文档写成迷宫。规范的价值不在于正确，而在于一致——同一批文档用同一套规矩，读的人才有预期。

第三件，别为了用而用。有些内容天生不适合 Markdown：需要复杂排版的宣传物料、需要精细图文混排的册子、需要大量批注和修订标记的协作场景，用专门的工具效率更高。Markdown 的强项是结构化文字，弱项是精细排版。认清这条边界，能省下很多拧巴的时间。

最后分享一个我一直在用的小技巧：新建文档时，先在开头放一段“写作目的”，用两三句话写清楚这份东西给谁看、要解决什么问题、大概多长。写的过程中如果卡住，回头看这三句话，往往就知道该删什么、该补什么。这段文字定稿时删掉，但它在你写不下去的那一刻，比任何写作方法都管用。