先说个我自己的经历。以前写公众号文章最崩溃的不是找选题也不是憋内容而是排版。标题用几号字、正文行距多少、引用怎么加背景色、代码块怎么不被编辑器吞掉……每个平台的按钮位置还不一样。一篇3000字的文章光调格式就能耗掉两个小时。后来我彻底切换到 Markdown 写作这个时间直接压缩到几乎没有。Markdown 就是用极简的文本符号完成排版你只需要记十几条语法规则就能让标题、加粗、列表、代码块、表格各归其位。这篇文章不聊虚的直接给你 10 个我在日常写作中真正高频用到的招式从换行这种最基础的细节到表格、图片、代码块、Mermaid 图表、目录生成这些进阶操作再到跨平台发布的兼容性避坑。不管你是写博客、写公众号还是写技术文档、做课程笔记这套方法都够用。如果你正准备学 Markdown或者已经写了一阵子但总觉得哪里别扭这篇指南值得你从头看到尾。1. 为什么 Markdown 能让你“排版秒杀 90% 博主”先想一个问题大部分博主排版不好看真的是因为不努力吗不是。真正的原因是他们在用 Word 那套“可视化排版”思路做内容每一次都要重新跟按钮较劲而且不同平台按钮还不一样效率自然低。Markdown 的核心逻辑完全不同纯文本 约定符号内容与样式分离。你写作的时候只负责用符号标注“这里是一级标题”“这里是加粗”“这里是个列表”具体渲染成什么样子交给工具去处理。同样一篇.md文件放到 GitHub 上是一种风格放进 Typora 是另一种风格发到支持 Markdown 的博客平台又会自动适配主题。这意味着你只需要写一次就能在无数地方复用同一套排版规则。跟 Word 对比一下会更直观。Word 的自由度很高但自由是把双刃剑你在这台电脑上调好的行距和字体换一台电脑打开就可能乱掉你精心设计的样式复制到公众号后台又会全部失效。而 Markdown 文件是纯文本用记事本都能打开任何设备任何系统都兼容配合 Git 还能做版本管理。这也是为什么程序员社区、技术文档体系里它几乎是事实标准。“秒杀 90% 博主”这个说法看似夸张其实背后是有逻辑的大多数人的文章排版混乱不是因为他们审美不行而是因为排版成本太高他们放弃了。一旦你把排版成本降到几乎为零你就有余力去注意标题层级是否清晰、段落节奏是否舒服、引用和列表用得是否克制。这些细节叠加起来文章自然会显得比大多数人专业。2. 写作前的准备工具怎么选、环境怎么配工具选不对后面所有技巧都白搭。我见过太多人拿着记事本写 Markdown写出来语法全对但没有任何实时反馈体验极差。根据不同的使用场景我推荐三套方案。第一套Typora适合纯写作者。它最大的特点是“所见即所得”输入#加空格标题立刻变成大字号输入**加粗**文字立刻变粗。你不需要记住任何预览快捷键写起来跟 Word 一样直觉。个人使用免费跨 Windows、macOS、Linux 平台。网上有人反馈 Typora 打开多个文件时只有一个窗口能响应这通常是软件本身的进程锁问题遇到这种情况先看后台是不是已经有一个 Typora 进程在运行结束掉再重新打开基本就能解决。第二套VSCode 插件适合程序员和技术写作者。VSCode 本身是个代码编辑器但装上 Markdown All in One、Markdown Preview Enhanced 这两个插件之后它就成了一个极其强大的 Markdown 写作环境。左侧写、右侧实时预览还支持自定义 CSS 主题。最关键是它天生支持 Git你可以像管理代码一样管理你的文章。如果你用 JetBrains 家的 IDE比如 IDEA它自带的 Markdown 编辑器也够用但如果你在 IDEA 里遇到“Your environment does not support JCEF”的报错说明当前环境缺少 JavaFX 组件去设置里把 Markdown 预览方式切换成内置浏览器模式或者安装一个 Markdown 增强插件就可以绕开这个问题。第三套飞书文档 / 语雀 / Notion适合团队协作。这类云文档天然支持多人编辑也内置了 Markdown 语法识别输入/可以唤起命令菜单粘贴 Markdown 内容也能自动转换。如果你用的是信创环境比如麒麟 V10 系统想找开源免费的本地 Markdown 工具可以试试思源笔记或 Mark Text都是跨平台开源项目体验不输付费软件。选型有一条核心原则不要为了“玩工具”而写作也不要因为工具难用而放弃写作。如果你是第一次接触我的建议是先用 Typora 写两周等语法熟练了再按需切换到 VSCode 或云文档。写作工具是为你服务的不是让你伺候它的。3. 基础功这四个招看起来简单却决定了文档的“底子”3.1 第一招段落与换行别再被“回车键”坑了这是 Markdown 新手翻车率最高的一处因为“回车键”在 Markdown 里有两个完全不同的含义。在 Word 里你按一下回车就是换一行但在 Markdown 里按一下回车只是“软换行”多数渲染器不会真的帮你换行而是把两行拼在一起中间加一个空格。想要真正换行有两个办法在上一行末尾敲两个空格再按回车标准 Markdown 的“硬换行”。更推荐的做法两段之间空一整行即连续按两次回车这会被识别为“新段落”段落之间会有明显的间距。这是第一行末尾有两个空格 这是第二行但它们是同一段落内的换行 这是新段落因为中间空了一行。我见过很多刚上手的人写出来的文档一段话中间敲了一堆回车结果渲染出来变成一坨连续文本。排查思路很简单先看是不是每段之间都空了一行再把行尾的零散空格删干净。记住一个口诀“空行分段空格换行”后面基本不会再踩这个坑。3.2 第二招标题体系先搭骨架再填肉Markdown 的一到六级标题分别用#到######表示#后面要加一个空格再接标题文字。但很多人只知道语法不知道“标题体系”这个概念导致文章结构混乱。写文章跟盖房子一样标题就是骨架。我的习惯是动笔之前先用标题把所有段落搭出来形成一个大纲然后再往里面填内容。这样你一眼就能看出逻辑是否通顺、有没有重复、节奏是否合理。标题使用有两个硬性规范。第一一个文档里最多只出现一个一级标题它通常是文章的总标题其他章节从二级标题开始。第二不要跳级。二级标题下面接三级标题再接四级层级必须有连续性。你从##跳到####渲染器不会报错但目录会缺块读者阅读时会觉得奇怪PDF 导出时导航也会乱。还有一个实用细节多级标题在文章内点击往往可以跳转这个机制依赖“锚点”。如果你用了标题没生成跳转通常是你用的渲染器没有开启自动锚点或者标题里有特殊字符冲突。后面讲目录生成的时候我会展开说。3.3 第三招加粗、斜体与行内代码让重点一眼可见这招最简单但“度”最难把握。加粗**文字**或__文字__斜体*文字*或_文字_行内代码代码我见过很多文章通篇都是加粗最后等于没有重点。正确的用法是加粗只用来标记一句话里最核心的几个词斜体用来表示语气、书名或轻微强调行内代码专门标记变量名、文件名、函数名、命令行参数这类技术性内容。这里需要**强调**的是config.yaml 里有一个*必须修改*的参数。行内代码最大的价值是防止格式冲突。比如你要写一个包含下划线的文件名README.md如果不加反引号下划线可能会被当成斜体标记导致显示异常。凡是涉及文件名、路径、API 名称的一律用行内代码包起来这是技术写作的基本素养。3.4 第四招链接与引用块“链接式写作”的起点Markdown 的链接语法有两种行内式[文字](URL)和引用式[文字][id]后者在文章底部统一维护链接地址适合链接特别多的文档。[百度](https://www.baidu.com) [百度][1] [1]: https://www.baidu.com引用块用开头表示这段文字是引用别人的话或补充说明。引用可以嵌套就是二级引用。在写作实践中我通常用引用块做三类事情引用外部资料或对话内容。放置“提示”“注意”这类专栏性文字。给文章加一段编者按或背景说明。 注意这个接口的返回结果有两种格式使用前需要先判断 code 字段。 更详细说明可以参考官方示例文档。引用块有个容易被忽略的细节和后面的文字之间要不要加空格多数渲染器不加也能识别但建议统一加一个空格兼容性更好也更清晰。4. 进阶功这六招让你的文章从“能用”变成“专业”4.1 第五招表格最容易被复制粘贴搞崩的一块Markdown 表格的语法结构很直观第一行是表头第二行是分隔行用---表示列:表示对齐方式第三行开始是数据。| 项目 | 价格 | 数量 | |------|-----:|:----:| | 苹果 | 5元 | 10 | | 香蕉 | 3元 | 20 |分隔行里的冒号位置决定对齐方式---左对齐---:右对齐:---:居中对齐。注意第二行的竖线数量不一定要和第一行完全严格对齐为了可读性我一般会手动补全但对渲染结果来说只要分隔行存在且列数一致就行。表格最容易翻车的场景是复制粘贴。很多人在飞书、语雀这类云文档里复制了一个表格想粘贴成 Markdown结果黏出来格式乱成一团。这时候不要手工一个一个调整直接用在线工具比如 tableconvert.com把网页表格转成 Markdown效率高得多。反过来你要把 Markdown 表格复制到 Excel 或飞书建议先用支持表格渲染的编辑器VSCode 预览、Typora、飞书文档打开再从渲染结果里复制。如果表格里要放竖线|需要用反斜杠转义\|否则表格会断列。表格单元格里要换行Markdown 原生不支持通常用br来解决。不过表格一旦复杂到需要用br才能表达清楚我一般会建议拆成列表或图文组合更易读。4.2 第六招代码块与 diff 高亮程序员博主的门面代码块用三个反引号包裹开始位置写上语言类型就能触发语法高亮function greet(name) { console.log(Hello, ${name}!); }如果你写的是技术教程关于代码块有几点容易被忽略。第一语言标注一定要写。不写语言标签代码就只是纯文本高亮效果全失阅读体验会差很多。第二diff 高亮是记录代码变更的利器GitHub 和很多编辑器都支持在语言标注里写diff比如- const oldVersion 1.0.0; const newVersion 2.0.0;第三代码块内的内容会被原样渲染Markdown 语法不会生效所以你在代码块里写br也好写**加粗**也好都会以纯文本形式展示。想展示“三个反引号”本身可以用四个反引号包裹外层。代码块不仅能放代码还能放命令行输出、JSON 配置、SQL 语句。只要是“希望读者以原文格式阅读”的内容都用代码块。代码特别长的时候可以配合折叠语法后面会讲让文章更清爽但注意有些平台对折叠支持有限长代码直接展示可能是更稳妥的方案。4.3 第七招图片引入别让图片拖垮整篇文章Markdown 的图片语法和链接很像只是在前面加了一个感叹号替代文字这一项很有用图片加载失败时会显示它屏幕阅读器也会读它所以不要偷懒不写。图片这块普遍有三个坑。第一个坑是路径问题。本地图片写的是相对路径比如images/1.png如果文章挪了目录或发布到线上路径就失效了。解决方案是如果文章要发布到公开平台用图床或对象存储的 URL如果只是本地文档保持相对路径不变不要再文件夹之间随便移动图片。第二个坑是图片尺寸控制。Markdown 原生不支持指定宽高图片原图多大就显示多大有时候会很突兀。解决办法是写一段 HTMLimg srcxxx width400多数渲染器都支持这种混写。第三个坑是图片文件体积。一张 5MB 的图片直接拖进文章不仅打开慢还会拖慢整个预览。发布前用工具压缩到几百 KB观感提升非常明显。img srchttps://example.com/image.png width400 alt示意图在飞书文档、小程序的富文本编辑器里粘贴本地图片通常会自动上传到平台图床但 Markdown 源文件里保存的依然是本地路径。所以如果你要跨平台发布最稳妥的流程是先决定图片的最终存储位置图床或 CDN再往文章里引用。4.4 第八招任务清单与折叠块让文档“活”起来任务清单是 Markdown 里比较“有交互感”的语法它利用的是 GitHub Flavored Markdown 的扩展- [ ] 待办事项一 - [x] 已完成事项这个语法支持在支持的平台上直接勾选适合写开发任务、采购清单、课程计划、周报进度用起来非常直观。要注意的是任务清单的- [ ]中括号里必须有一个空格- [x]是小写 x大小写和空格不对会导致无法渲染成可选状态而变成普通列表。折叠块是比较“冷门”但很实用的一招。它本质上是在 Markdown 里混用 HTML 的details标签details summary点击展开详情/summary 这里是折叠后才会显示的内容可以放表格、代码块、图片等。 /detailsGitHub、语雀、Hexo 等很多平台都支持这个语法适合放“参考答案”“进阶补充”“附录资料”这类读者想看又不一定总是要看的内容。折叠块里再嵌套 Markdown 语法时要注意分隔空行否则可能解析失败。4.5 第九招Mermaid 图表流程图也能用代码写很多人在文档里画流程图第一反应是打开 Draw.io 或者 ProcessOn 拖拽图形。但如果你用的是支持 Mermaid 的 Markdown 编辑器完全可以用纯代码画图改动文本即可重新渲染不用鼠标拖来拖去。Mermaid 支持流程图、时序图、甘特图、状态图等。比如一个最简单的流程图graph TD A[开始] -- B{是否有权限?} B -- 是 -- C[进入系统] B -- 否 -- D[拒绝访问]在 Typora 和 VSCode 预览里这类代码块会自动渲染成图表非常方便。这里有一个痛点在飞书文档里直接粘贴 mermaid 代码块默认是不会渲染的。需要在飞书里安装“Mermaid 画板”或类似的第三方插件然后把代码粘贴到插件里才能生成图片或者自己在本地渲染好再以图片方式上传。同样是 Markdown 文件放到 GitHub 上 Mermaid 就可以原生渲染放到某些博客系统上则不一定支持。因此发布前一定要确认目标平台的 Mermaid 支持情况否则就会出现“代码块露在外面”的尴尬。Mermaid 的语法本身不难核心是记住不同类型图表的关键字graph是流程图sequenceDiagram是时序图gantt是甘特图。画复杂图之前先画简化版确认语法无误再加细节是效率最高的方式。4.6 第十招目录与导航长文的阅读体验救星文章一长读者很容易迷路。这时候目录就是阅读体验的救星。很多 Markdown 渲染器会根据标题自动生成目录TOCTable of Contents但不同工具入口不一样。VSCode 里想要让目录显示出来最简单的方法是把内置的大纲面板打开工具栏“查看 - 打开视图”在资源管理器侧边栏里找到“大纲”它会根据文章标题自动生成层级列表点击即可跳转。想要让目录出现在预览区可以用 Markdown Preview Enhanced 插件或者用 Markdown All in One 的“生成目录”命令它会在光标处插入一个[[TOC]]标记预览时自动替换成完整目录。Typora 的做法是在文章开头插入[TOC]渲染后即可生成可点击目录。有的平台支持[[_TOC_]]比如 GitLab 和语雀或!-- TOC --注释块部分编辑器插件会自动扫描全文生成目录。我的建议是发布前先在编辑器里开启大纲面板从一级标题往下扫一遍检查层级是否连续、标题是否重复、有没有空标题。这一步比任何排版美化都管用。标题是文章的地图地图画清楚了读者才有耐心读完你的长文。5. 跨平台渲染的兼容性为什么同一个文件换个地方就“炸”这是我最想强调的一章。Markdown 最大的卖点是“一次编写到处渲染”但现实是不同平台对 Markdown 语法的支持程度并不一致同一个.md文件在 Typora 里显示完美发到某个小程序后台可能就变了样。举个例子Typora、GitHub 和飞书文档对任务列表- [ ]都支持勾选交互但微信公众号后台原生编辑器不支持 Markdown你需要把 Markdown 转换成带样式的 HTML 再粘贴。vue 解析 Markdown 时用的库不同支持程度也不一样markdown-it、marked、remark各有各的边界。小程序里显示 Markdown通常需要引入towxml或rich-text组件来解析渲染而有些进阶语法比如表格、任务列表可能不支持。所以发布前一定要做一次“平台适配检查”平台常见坑GitHub / GitLabMermaid 支持但部分扩展语法有差异Typora[TOC] 只在 Typora 生效VSCode 预览默认不渲染 Mermaid需要插件飞书文档Mermaid 不默认渲染需插件微信公众号不直接支持 MD需转 HTML小程序需自行引入解析库部分语法不支持知乎 / 语雀部分 GFM 扩展语法支持不全有一个通用兜底方案如果目标平台实在不支持某些高级语法那就用“降级策略”——Mermaid 不渲染就导出成图片折叠块不支持就直接展开写任务列表不支持就写成普通列表。内容本身不变只是呈现方式做兼容处理。6. 一套完整的 Markdown 写作工作流学完语法最后要落地到日常写作。我自己的完整流程是这样的先用 5 分钟列标题大纲。只写一到三级标题不考虑内容先把文章脉络理清楚。按标题填充内容。过程中只关注表达不纠结格式。倒回去统一处理图片和链接。图片先压缩再引用链接逐个验证是否能打开。检查目录和层级。打开大纲面板从上到下扫一遍。导出或发布。公众号场景用工具把 Markdown 转成带样式的 HTML 再粘贴技术博客直接传.md文件需要交 Word 文档时用 Pandoc 一键转换pandoc article.md -o article.docx如果觉得 Pandoc 命令行麻烦可以搜一下专门的 Markdown 转 Word 工作流甚至可以在自动化平台上把这个转换过程编排成一个固定流程每次只要拖动文件进去就能得到排版好的 Word。同步和备份。我通常把文章仓库放在 Git 仓库里每次修改都有版本记录写坏了可以随时回滚。你也可以用坚果云、iCloud 或者自建网盘同步.md文件纯文本格式让备份成本极低。这一套流程走下来一篇 5000 字的深度文从零到发布基本控制在两三个小时以内其中大部分时间花在写内容而不是排版上。7. 最后再聊几点我的个人体会写 Markdown 写了这么多年有三点碎碎念想分享。第一快捷键值得花十分钟记一下。很多编辑器里Ctrl/CommandB 是加粗、Ctrl/CommandK 是插入链接、Ctrl/CommandShiftC 是行内代码把常用几个记熟了写作速度还能再上一层楼。第二写 Markdown 的边际收益是累积的。起初你可能会觉得“记这些符号还不如直接点按钮”但三个月后当别人还在为不同平台的排版规则焦头烂额时你已经能在一分钟内把一篇格式工整的文章发出去。这种差距不是玄学是工具思维带来的复利。第三工具是手段不是目的。不要为了“折腾插件”而花一整晚配置编辑器也不要在“哪个编辑器最好用”这种问题上纠结太久。真正重要的是你的内容本身。Markdown 给你腾出了时间和精力你应该把它们用在选题、观点、叙事和逻辑上那才是让一篇文章从“排版好看”升级到“真正值得读”的地方。
先说个我自己的经历。以前写公众号文章最崩溃的不是找选题也不是憋内容而是排版。标题用几号字、正文行距多少、引用怎么加背景色、代码块怎么不被编辑器吞掉……每个平台的按钮位置还不一样。一篇3000字的文章光调格式就能耗掉两个小时。后来我彻底切换到 Markdown 写作这个时间直接压缩到几乎没有。Markdown 就是用极简的文本符号完成排版你只需要记十几条语法规则就能让标题、加粗、列表、代码块、表格各归其位。这篇文章不聊虚的直接给你 10 个我在日常写作中真正高频用到的招式从换行这种最基础的细节到表格、图片、代码块、Mermaid 图表、目录生成这些进阶操作再到跨平台发布的兼容性避坑。不管你是写博客、写公众号还是写技术文档、做课程笔记这套方法都够用。如果你正准备学 Markdown或者已经写了一阵子但总觉得哪里别扭这篇指南值得你从头看到尾。1. 为什么 Markdown 能让你“排版秒杀 90% 博主”先想一个问题大部分博主排版不好看真的是因为不努力吗不是。真正的原因是他们在用 Word 那套“可视化排版”思路做内容每一次都要重新跟按钮较劲而且不同平台按钮还不一样效率自然低。Markdown 的核心逻辑完全不同纯文本 约定符号内容与样式分离。你写作的时候只负责用符号标注“这里是一级标题”“这里是加粗”“这里是个列表”具体渲染成什么样子交给工具去处理。同样一篇.md文件放到 GitHub 上是一种风格放进 Typora 是另一种风格发到支持 Markdown 的博客平台又会自动适配主题。这意味着你只需要写一次就能在无数地方复用同一套排版规则。跟 Word 对比一下会更直观。Word 的自由度很高但自由是把双刃剑你在这台电脑上调好的行距和字体换一台电脑打开就可能乱掉你精心设计的样式复制到公众号后台又会全部失效。而 Markdown 文件是纯文本用记事本都能打开任何设备任何系统都兼容配合 Git 还能做版本管理。这也是为什么程序员社区、技术文档体系里它几乎是事实标准。“秒杀 90% 博主”这个说法看似夸张其实背后是有逻辑的大多数人的文章排版混乱不是因为他们审美不行而是因为排版成本太高他们放弃了。一旦你把排版成本降到几乎为零你就有余力去注意标题层级是否清晰、段落节奏是否舒服、引用和列表用得是否克制。这些细节叠加起来文章自然会显得比大多数人专业。2. 写作前的准备工具怎么选、环境怎么配工具选不对后面所有技巧都白搭。我见过太多人拿着记事本写 Markdown写出来语法全对但没有任何实时反馈体验极差。根据不同的使用场景我推荐三套方案。第一套Typora适合纯写作者。它最大的特点是“所见即所得”输入#加空格标题立刻变成大字号输入**加粗**文字立刻变粗。你不需要记住任何预览快捷键写起来跟 Word 一样直觉。个人使用免费跨 Windows、macOS、Linux 平台。网上有人反馈 Typora 打开多个文件时只有一个窗口能响应这通常是软件本身的进程锁问题遇到这种情况先看后台是不是已经有一个 Typora 进程在运行结束掉再重新打开基本就能解决。第二套VSCode 插件适合程序员和技术写作者。VSCode 本身是个代码编辑器但装上 Markdown All in One、Markdown Preview Enhanced 这两个插件之后它就成了一个极其强大的 Markdown 写作环境。左侧写、右侧实时预览还支持自定义 CSS 主题。最关键是它天生支持 Git你可以像管理代码一样管理你的文章。如果你用 JetBrains 家的 IDE比如 IDEA它自带的 Markdown 编辑器也够用但如果你在 IDEA 里遇到“Your environment does not support JCEF”的报错说明当前环境缺少 JavaFX 组件去设置里把 Markdown 预览方式切换成内置浏览器模式或者安装一个 Markdown 增强插件就可以绕开这个问题。第三套飞书文档 / 语雀 / Notion适合团队协作。这类云文档天然支持多人编辑也内置了 Markdown 语法识别输入/可以唤起命令菜单粘贴 Markdown 内容也能自动转换。如果你用的是信创环境比如麒麟 V10 系统想找开源免费的本地 Markdown 工具可以试试思源笔记或 Mark Text都是跨平台开源项目体验不输付费软件。选型有一条核心原则不要为了“玩工具”而写作也不要因为工具难用而放弃写作。如果你是第一次接触我的建议是先用 Typora 写两周等语法熟练了再按需切换到 VSCode 或云文档。写作工具是为你服务的不是让你伺候它的。3. 基础功这四个招看起来简单却决定了文档的“底子”3.1 第一招段落与换行别再被“回车键”坑了这是 Markdown 新手翻车率最高的一处因为“回车键”在 Markdown 里有两个完全不同的含义。在 Word 里你按一下回车就是换一行但在 Markdown 里按一下回车只是“软换行”多数渲染器不会真的帮你换行而是把两行拼在一起中间加一个空格。想要真正换行有两个办法在上一行末尾敲两个空格再按回车标准 Markdown 的“硬换行”。更推荐的做法两段之间空一整行即连续按两次回车这会被识别为“新段落”段落之间会有明显的间距。这是第一行末尾有两个空格 这是第二行但它们是同一段落内的换行 这是新段落因为中间空了一行。我见过很多刚上手的人写出来的文档一段话中间敲了一堆回车结果渲染出来变成一坨连续文本。排查思路很简单先看是不是每段之间都空了一行再把行尾的零散空格删干净。记住一个口诀“空行分段空格换行”后面基本不会再踩这个坑。3.2 第二招标题体系先搭骨架再填肉Markdown 的一到六级标题分别用#到######表示#后面要加一个空格再接标题文字。但很多人只知道语法不知道“标题体系”这个概念导致文章结构混乱。写文章跟盖房子一样标题就是骨架。我的习惯是动笔之前先用标题把所有段落搭出来形成一个大纲然后再往里面填内容。这样你一眼就能看出逻辑是否通顺、有没有重复、节奏是否合理。标题使用有两个硬性规范。第一一个文档里最多只出现一个一级标题它通常是文章的总标题其他章节从二级标题开始。第二不要跳级。二级标题下面接三级标题再接四级层级必须有连续性。你从##跳到####渲染器不会报错但目录会缺块读者阅读时会觉得奇怪PDF 导出时导航也会乱。还有一个实用细节多级标题在文章内点击往往可以跳转这个机制依赖“锚点”。如果你用了标题没生成跳转通常是你用的渲染器没有开启自动锚点或者标题里有特殊字符冲突。后面讲目录生成的时候我会展开说。3.3 第三招加粗、斜体与行内代码让重点一眼可见这招最简单但“度”最难把握。加粗**文字**或__文字__斜体*文字*或_文字_行内代码代码我见过很多文章通篇都是加粗最后等于没有重点。正确的用法是加粗只用来标记一句话里最核心的几个词斜体用来表示语气、书名或轻微强调行内代码专门标记变量名、文件名、函数名、命令行参数这类技术性内容。这里需要**强调**的是config.yaml 里有一个*必须修改*的参数。行内代码最大的价值是防止格式冲突。比如你要写一个包含下划线的文件名README.md如果不加反引号下划线可能会被当成斜体标记导致显示异常。凡是涉及文件名、路径、API 名称的一律用行内代码包起来这是技术写作的基本素养。3.4 第四招链接与引用块“链接式写作”的起点Markdown 的链接语法有两种行内式[文字](URL)和引用式[文字][id]后者在文章底部统一维护链接地址适合链接特别多的文档。[百度](https://www.baidu.com) [百度][1] [1]: https://www.baidu.com引用块用开头表示这段文字是引用别人的话或补充说明。引用可以嵌套就是二级引用。在写作实践中我通常用引用块做三类事情引用外部资料或对话内容。放置“提示”“注意”这类专栏性文字。给文章加一段编者按或背景说明。 注意这个接口的返回结果有两种格式使用前需要先判断 code 字段。 更详细说明可以参考官方示例文档。引用块有个容易被忽略的细节和后面的文字之间要不要加空格多数渲染器不加也能识别但建议统一加一个空格兼容性更好也更清晰。4. 进阶功这六招让你的文章从“能用”变成“专业”4.1 第五招表格最容易被复制粘贴搞崩的一块Markdown 表格的语法结构很直观第一行是表头第二行是分隔行用---表示列:表示对齐方式第三行开始是数据。| 项目 | 价格 | 数量 | |------|-----:|:----:| | 苹果 | 5元 | 10 | | 香蕉 | 3元 | 20 |分隔行里的冒号位置决定对齐方式---左对齐---:右对齐:---:居中对齐。注意第二行的竖线数量不一定要和第一行完全严格对齐为了可读性我一般会手动补全但对渲染结果来说只要分隔行存在且列数一致就行。表格最容易翻车的场景是复制粘贴。很多人在飞书、语雀这类云文档里复制了一个表格想粘贴成 Markdown结果黏出来格式乱成一团。这时候不要手工一个一个调整直接用在线工具比如 tableconvert.com把网页表格转成 Markdown效率高得多。反过来你要把 Markdown 表格复制到 Excel 或飞书建议先用支持表格渲染的编辑器VSCode 预览、Typora、飞书文档打开再从渲染结果里复制。如果表格里要放竖线|需要用反斜杠转义\|否则表格会断列。表格单元格里要换行Markdown 原生不支持通常用br来解决。不过表格一旦复杂到需要用br才能表达清楚我一般会建议拆成列表或图文组合更易读。4.2 第六招代码块与 diff 高亮程序员博主的门面代码块用三个反引号包裹开始位置写上语言类型就能触发语法高亮function greet(name) { console.log(Hello, ${name}!); }如果你写的是技术教程关于代码块有几点容易被忽略。第一语言标注一定要写。不写语言标签代码就只是纯文本高亮效果全失阅读体验会差很多。第二diff 高亮是记录代码变更的利器GitHub 和很多编辑器都支持在语言标注里写diff比如- const oldVersion 1.0.0; const newVersion 2.0.0;第三代码块内的内容会被原样渲染Markdown 语法不会生效所以你在代码块里写br也好写**加粗**也好都会以纯文本形式展示。想展示“三个反引号”本身可以用四个反引号包裹外层。代码块不仅能放代码还能放命令行输出、JSON 配置、SQL 语句。只要是“希望读者以原文格式阅读”的内容都用代码块。代码特别长的时候可以配合折叠语法后面会讲让文章更清爽但注意有些平台对折叠支持有限长代码直接展示可能是更稳妥的方案。4.3 第七招图片引入别让图片拖垮整篇文章Markdown 的图片语法和链接很像只是在前面加了一个感叹号替代文字这一项很有用图片加载失败时会显示它屏幕阅读器也会读它所以不要偷懒不写。图片这块普遍有三个坑。第一个坑是路径问题。本地图片写的是相对路径比如images/1.png如果文章挪了目录或发布到线上路径就失效了。解决方案是如果文章要发布到公开平台用图床或对象存储的 URL如果只是本地文档保持相对路径不变不要再文件夹之间随便移动图片。第二个坑是图片尺寸控制。Markdown 原生不支持指定宽高图片原图多大就显示多大有时候会很突兀。解决办法是写一段 HTMLimg srcxxx width400多数渲染器都支持这种混写。第三个坑是图片文件体积。一张 5MB 的图片直接拖进文章不仅打开慢还会拖慢整个预览。发布前用工具压缩到几百 KB观感提升非常明显。img srchttps://example.com/image.png width400 alt示意图在飞书文档、小程序的富文本编辑器里粘贴本地图片通常会自动上传到平台图床但 Markdown 源文件里保存的依然是本地路径。所以如果你要跨平台发布最稳妥的流程是先决定图片的最终存储位置图床或 CDN再往文章里引用。4.4 第八招任务清单与折叠块让文档“活”起来任务清单是 Markdown 里比较“有交互感”的语法它利用的是 GitHub Flavored Markdown 的扩展- [ ] 待办事项一 - [x] 已完成事项这个语法支持在支持的平台上直接勾选适合写开发任务、采购清单、课程计划、周报进度用起来非常直观。要注意的是任务清单的- [ ]中括号里必须有一个空格- [x]是小写 x大小写和空格不对会导致无法渲染成可选状态而变成普通列表。折叠块是比较“冷门”但很实用的一招。它本质上是在 Markdown 里混用 HTML 的details标签details summary点击展开详情/summary 这里是折叠后才会显示的内容可以放表格、代码块、图片等。 /detailsGitHub、语雀、Hexo 等很多平台都支持这个语法适合放“参考答案”“进阶补充”“附录资料”这类读者想看又不一定总是要看的内容。折叠块里再嵌套 Markdown 语法时要注意分隔空行否则可能解析失败。4.5 第九招Mermaid 图表流程图也能用代码写很多人在文档里画流程图第一反应是打开 Draw.io 或者 ProcessOn 拖拽图形。但如果你用的是支持 Mermaid 的 Markdown 编辑器完全可以用纯代码画图改动文本即可重新渲染不用鼠标拖来拖去。Mermaid 支持流程图、时序图、甘特图、状态图等。比如一个最简单的流程图graph TD A[开始] -- B{是否有权限?} B -- 是 -- C[进入系统] B -- 否 -- D[拒绝访问]在 Typora 和 VSCode 预览里这类代码块会自动渲染成图表非常方便。这里有一个痛点在飞书文档里直接粘贴 mermaid 代码块默认是不会渲染的。需要在飞书里安装“Mermaid 画板”或类似的第三方插件然后把代码粘贴到插件里才能生成图片或者自己在本地渲染好再以图片方式上传。同样是 Markdown 文件放到 GitHub 上 Mermaid 就可以原生渲染放到某些博客系统上则不一定支持。因此发布前一定要确认目标平台的 Mermaid 支持情况否则就会出现“代码块露在外面”的尴尬。Mermaid 的语法本身不难核心是记住不同类型图表的关键字graph是流程图sequenceDiagram是时序图gantt是甘特图。画复杂图之前先画简化版确认语法无误再加细节是效率最高的方式。4.6 第十招目录与导航长文的阅读体验救星文章一长读者很容易迷路。这时候目录就是阅读体验的救星。很多 Markdown 渲染器会根据标题自动生成目录TOCTable of Contents但不同工具入口不一样。VSCode 里想要让目录显示出来最简单的方法是把内置的大纲面板打开工具栏“查看 - 打开视图”在资源管理器侧边栏里找到“大纲”它会根据文章标题自动生成层级列表点击即可跳转。想要让目录出现在预览区可以用 Markdown Preview Enhanced 插件或者用 Markdown All in One 的“生成目录”命令它会在光标处插入一个[[TOC]]标记预览时自动替换成完整目录。Typora 的做法是在文章开头插入[TOC]渲染后即可生成可点击目录。有的平台支持[[_TOC_]]比如 GitLab 和语雀或!-- TOC --注释块部分编辑器插件会自动扫描全文生成目录。我的建议是发布前先在编辑器里开启大纲面板从一级标题往下扫一遍检查层级是否连续、标题是否重复、有没有空标题。这一步比任何排版美化都管用。标题是文章的地图地图画清楚了读者才有耐心读完你的长文。5. 跨平台渲染的兼容性为什么同一个文件换个地方就“炸”这是我最想强调的一章。Markdown 最大的卖点是“一次编写到处渲染”但现实是不同平台对 Markdown 语法的支持程度并不一致同一个.md文件在 Typora 里显示完美发到某个小程序后台可能就变了样。举个例子Typora、GitHub 和飞书文档对任务列表- [ ]都支持勾选交互但微信公众号后台原生编辑器不支持 Markdown你需要把 Markdown 转换成带样式的 HTML 再粘贴。vue 解析 Markdown 时用的库不同支持程度也不一样markdown-it、marked、remark各有各的边界。小程序里显示 Markdown通常需要引入towxml或rich-text组件来解析渲染而有些进阶语法比如表格、任务列表可能不支持。所以发布前一定要做一次“平台适配检查”平台常见坑GitHub / GitLabMermaid 支持但部分扩展语法有差异Typora[TOC] 只在 Typora 生效VSCode 预览默认不渲染 Mermaid需要插件飞书文档Mermaid 不默认渲染需插件微信公众号不直接支持 MD需转 HTML小程序需自行引入解析库部分语法不支持知乎 / 语雀部分 GFM 扩展语法支持不全有一个通用兜底方案如果目标平台实在不支持某些高级语法那就用“降级策略”——Mermaid 不渲染就导出成图片折叠块不支持就直接展开写任务列表不支持就写成普通列表。内容本身不变只是呈现方式做兼容处理。6. 一套完整的 Markdown 写作工作流学完语法最后要落地到日常写作。我自己的完整流程是这样的先用 5 分钟列标题大纲。只写一到三级标题不考虑内容先把文章脉络理清楚。按标题填充内容。过程中只关注表达不纠结格式。倒回去统一处理图片和链接。图片先压缩再引用链接逐个验证是否能打开。检查目录和层级。打开大纲面板从上到下扫一遍。导出或发布。公众号场景用工具把 Markdown 转成带样式的 HTML 再粘贴技术博客直接传.md文件需要交 Word 文档时用 Pandoc 一键转换pandoc article.md -o article.docx如果觉得 Pandoc 命令行麻烦可以搜一下专门的 Markdown 转 Word 工作流甚至可以在自动化平台上把这个转换过程编排成一个固定流程每次只要拖动文件进去就能得到排版好的 Word。同步和备份。我通常把文章仓库放在 Git 仓库里每次修改都有版本记录写坏了可以随时回滚。你也可以用坚果云、iCloud 或者自建网盘同步.md文件纯文本格式让备份成本极低。这一套流程走下来一篇 5000 字的深度文从零到发布基本控制在两三个小时以内其中大部分时间花在写内容而不是排版上。7. 最后再聊几点我的个人体会写 Markdown 写了这么多年有三点碎碎念想分享。第一快捷键值得花十分钟记一下。很多编辑器里Ctrl/CommandB 是加粗、Ctrl/CommandK 是插入链接、Ctrl/CommandShiftC 是行内代码把常用几个记熟了写作速度还能再上一层楼。第二写 Markdown 的边际收益是累积的。起初你可能会觉得“记这些符号还不如直接点按钮”但三个月后当别人还在为不同平台的排版规则焦头烂额时你已经能在一分钟内把一篇格式工整的文章发出去。这种差距不是玄学是工具思维带来的复利。第三工具是手段不是目的。不要为了“折腾插件”而花一整晚配置编辑器也不要在“哪个编辑器最好用”这种问题上纠结太久。真正重要的是你的内容本身。Markdown 给你腾出了时间和精力你应该把它们用在选题、观点、叙事和逻辑上那才是让一篇文章从“排版好看”升级到“真正值得读”的地方。
` 深度指南：为键设置绝对过期时间戳)
