不用装一堆软件也不用记复杂的标签一个纯文本文件就能写出结构清晰的文档这事儿放在十年前我还真不太信。但 Markdown 就是这么干的了它用极少的标记符号把标题、列表、代码、表格这些排版需求全部覆盖写完一个.md文件既能直接阅读也能一键转成 HTML、PDF、Word。我用了几年下来最大的感受就是写 Markdown 会上瘾因为它把「排版」这件事的负担从大脑里彻底删掉了。这份笔记不只是列语法我会结合自己实际踩过的坑、试过的工具把 Markdown 基础语法、编辑器选型、常见问题都讲透。适合刚接触 Markdown 的新手也适合已经用了一段时间但想补全细节、提升效率的老手。1. 为什么学 Markdown它到底解决了什么问题先说个扎心的场景。以前写文档用 Word标题字号调了半天发给同事后格式全乱图片乱跑目录一更新直接崩。后来写博客用 HTML标题要写h1加粗要写strong代码块要写precode一篇长文写完标签比内容还多心态直接爆炸。Markdown 的思路完全反过来它不在排版上给你花哨的选项而是用一套极简的标记规则让你像写纯文本一样写文档。你只需要知道#是标题、**是加粗、是代码块剩下的渲染工作交给工具。这种设计的核心哲学是创作者专注于内容和结构格式由统一规则自动生成。这套思路解决了我三个实际痛点格式统一不管在哪个平台打开.md文件只要解析器符合 CommonMark 或 GFMGitHub Flavored Markdown规范渲染出来的结构就一样。不会出现 Word 那种「我这边是两页你那边变成三页」的尴尬。迁移成本低Markdown 是纯文本任何一个文本编辑器都能打开。就算哪天 Typora 不能用了、VS Code 没装插件了文件内容依然完整数据永远掌握在自己手里。通用性强GitHub 的 README、博客平台、笔记软件、技术文档、甚至邮件客户端都支持 Markdown。学会一套语法到处都能用不用每换一个平台就重新学一套排版规则。还有人会问Markdown 和 HTML 是什么关系其实 Markdown 是 HTML 的简化书写层最终渲染时会被转换成 HTML。如果你把 Markdown 的标记符号当成一种「快捷键」理解起来就不难#约等于h1**约等于strong*约等于em。我后面讲渲染工具的时候会专门说这个转换过程有兴趣的可以先记着。1.1 Markdown 的适用场景我个人的经验是Markdown 适合这些场景技术文档、README、项目说明个人笔记、知识库Obsidian、Notion、语雀都支持博客文章、公众号排版配合编辑器转换日常邮件、协作文档部分工具支持 Markdown 语法不适合的场景也有如果你需要非常复杂的排版比如论文的交叉引用、特殊页眉页脚、精确到毫米的版式控制那还是得回到 Word 或 LaTeX。Markdown 的目标是把 80% 的日常排版需求做到极简剩下 20% 的极端需求本来就该交给专业工具。1.2 小白需要先搞懂的 3 个基础概念在正式学语法之前有三个概念一定要先建立起来不然后面会被各种术语绕晕。第一个概念纯文本与渲染后的效果是两回事。你在编辑器里看到的# 标题是原文渲染后变成大号加粗的标题才是显示效果。很多新手以为在 Typora 里按一下回车就能换行结果发现渲染后还是连在一起的这就是混淆了「源码层」和「渲染层」。第二个概念Markdown 有不同方言。最基础的是 CommonMarkGitHub 上用的是 GFMTypora 还支持一些扩展语法比如上标、下标、高亮。基础语法大家互通但扩展语法换工具后可能不兼容。第三个概念Markdown 本质是转换。你写的是文本但任何编辑器最终都会把它转成 HTML 或富文本。理解这一点后你就明白为什么 Markdown 能导出成那么多格式了——它只是中间层出口是万能的。2. Markdown 基础语法逐个拆解这章是整篇笔记的正文我把最常用的语法分成两组第一组是天天要用的不会写就没法干活第二组是高频但容易出错的值得单独拎出来讲。2.1 标题怎么用才规范标题用#表示一级标题是一个#二级是两个##最多支持六级。注意#后面要加一个空格否则某些解析器会把它识别成普通文本。# 一级标题 ## 二级标题 ### 三级标题 #### 四级标题 ##### 五级标题 ###### 六级标题实操时有个习惯我建议你养成一篇文章只有一个一级标题其他层级顺序递进不要跳级。比如#之后直接用###结构上看起来没什么但如果你之后要自动生成目录跳级会导致导航混乱。写文章之前先花 30 秒列一下大纲把标题层级想清楚后面改起来会省很多事。还有一个细节在 Typora 里如果你在标题行按回车会自动生成一个新的同级标题连续按两次回车则会退出标题状态回到正文。这个快捷键配合写作很爽但新手经常误触搞不清自己为什么突然在写标题。记住标题行结束后按一次回车是继续写标题按两次才是写正文。2.2 段落与换行最容易栽的坑Markdown 的段落规则非常简单两个段落之间用空行分隔。如果你想在同一段落内换行需要在行尾加两个空格再回车或者用 HTML 的br标签。这可能是新手最常踩的坑。在 Typora 里直接按Shift Enter是软换行渲染后会换行但如果你用 VS Code 或在线编辑器按回车后渲染出来可能没有换行效果。原因就是Markdown 把单个换行符当成空格处理只有空行才表示段落分隔。我自己的习惯是正文段落之间永远用空行隔开显式换行尽量用br不用行尾两个空格。因为行尾两个空格不可见别人复制你的源码时容易弄丢而br是一眼能看出来的。再补充一个场景很多人写公众号或知乎文章时希望段落之间留出间隔习惯在每段后加一个空行。这个在 Markdown 里是标准做法渲染后就是段落间距不用手动调样式。2.3 强调语法加粗、斜体、删除线Markdown 的强调语法就三个**加粗** *斜体* ~~删除线~~注意两个细节。第一加粗和斜体可以嵌套比如***加粗斜体***会渲染成加粗加斜体。第二符号和文字之间要紧贴不能有空格** 加粗 **这种写法在部分解析器里不会生效。我在实际写文档时强调的使用原则是能不用就不用。如果通篇都是加粗读者就分不清重点了。加粗适合标注关键结论斜体适合补充说明或书名删除线适合表示「已废弃但保留查看」。还有一个 GFM 特有的语法如果你在文字两侧各加两个波浪号~~部分编辑器支持删除线GitHub、Typora 都支持。但注意这个语法不是 CommonMark 标准换了编辑器可能不渲染。2.4 列表有序、无序、嵌套、任务清单列表是 Markdown 里使用频率最高的语法之一写文档、列待办、整理要点都离不开它。无序列表用-、*或加空格开头- 苹果 - 香蕉 - 橙子有序列表用数字.加空格开头1. 第一步 2. 第二步 3. 第三步嵌套列表用缩进实现注意子列表要和父列表之间加两个或四个空格缩进- 水果 - 苹果 - 香蕉 - 蔬菜 - 白菜 - 萝卜任务列表是 GFM 扩展语法写法如下- [ ] 待办事项 - [x] 已完成事项我有个切身教训有序列表的序号其实可以乱写Markdown 渲染时会自动按顺序编号。比如你写1. a、3. b、2. c渲染出来仍然是 1、2、3。这很方便但也会让人偷懒。如果你在团队协作中维护文档建议从 1 开始手动编号这样在源码里就能直接看出顺序不需要渲染器帮你纠错。另外嵌套列表容易出问题的点是在列表项里塞多个段落。如果你想在某个列表项下面继续写字必须保证这些段落也在缩进范围内而且中间要用空行隔开否则渲染会出错。2.5 链接和图片写对地址是关键链接的语法是[显示文字](URL)图片的语法是在前面加一个感叹号。两者都支持相对路径。[百度](https://www.baidu.com) 这里有两个容易踩的坑。第一个坑链接地址里如果有空格或特殊字符要用包起来或者对空格做 URL 编码。比如[我的文档](./my file.md)这种写法在某些解析器里才能正确识别。第二个坑图片相对路径的根目录。很多新手在本地写.md文件时图片能正常显示但一提交到 GitHub 或换一台电脑图片就全部裂开了。原因是你用了绝对路径比如C:\Users\xxx\Pictures\1.png换设备后路径不存在了。正确做法是把图片放在和.md文件同级的images文件夹下用相对路径引用并把整个文件夹一起迁移。关于图片我再补充一个进阶技巧如果你不想用相对路径可以先把图片上传到图床然后用 URL 引用。图床的好处是换设备、换平台都不用担心图片丢失坏处是如果图床服务关闭图片还是会挂。稳妥的做法是本地保留原始文件 图床只用来渲染。2.6 代码和代码块写错一个符号就全废行内代码用一个反引号包裹这是 code 示例代码块用三个反引号包裹并在开头标注语言类型python print(hello world) 注意反引号的位置非常关键。新手经常犯的错是开了三个反引号但忘记闭合导致后面所有内容都被识别成代码块整个文档排版瞬间崩掉。写代码块时一定要检查「开三个」和「关三个」数目一致。标注语言类型有什么用渲染器会根据语言类型做语法高亮比如我上面标注了python渲染后print函数就是高亮的。如果你不标注语言类型大部分编辑器只会用灰色底色显示视觉效果差很多。常用标注python、java、javascript、bash、sql、html、css。还有一个比较特殊的情况如果你想在代码块里显示三个反引号就需要用四个反引号作为围栏。这个平时用不到但如果你写文档时恰好要展示 Markdown 语法本身比如写教学笔记就会遇到。2.7 引用用它区分「别人说的」和「我说的」引用用表示适合引用外部资料或突出某段话 这是一段引用 第二行引用引用可以嵌套比如 嵌套引用。也可以和其他语法混用比如引用里加标题、加列表、加代码块。我的使用习惯是技术文档里引用一般用于标注「参考来源」或「注意事项」。比如我会写 注意这段 API 在 2.0 版本已废弃请使用新接口替代。但不要过度使用引用。有些新手把正文内容全部包在引用块里渲染出来就是满屏的灰色竖线阅读体验非常差。引用是「特殊标记」不是「排版主体」。2.8 表格基础语法不复杂复杂在复制粘贴表格是 Markdown 里稍显繁琐的语法但掌握规律后很好用。最基本的结构是表头、分隔行、数据行。| 姓名 | 年龄 | 城市 | | ---- | ---- | ---- | | 张三 | 25 | 上海 | | 李四 | 30 | 北京 |注意分隔行至少要有---|的数目要和表头一致。渲染效果是把表格左右对齐如果你写:---是左对齐---:是右对齐:---:是居中。表格最让人头疼的是「复制粘贴」。很多人在 Typora 中写好表格直接 CtrlC 粘贴到 Excel结果发现全乱了。原因在于 Typora 复制到剪贴板的是带表格格式的 HTML 数据直接粘贴到 Excel 有时会丢行列结构。我实测下来先在 Typora 里用 Markdown 源码模式全选复制再粘贴到 Excel再手动分列成功率最高。或者干脆用在线转换工具把 Markdown 表格转成 CSV 再导入 Excel。还有一点表格内如果要换行可以用br标签。比如| 功能 | 说明 | | ---- | ---- | | 换行 | 第一行br第二行 |这在某些编辑器里渲染正常但并不是所有解析器都支持所以表格内尽量别塞太长文本保持简洁。2.9 分割线、HTML 混写、转义字符分割线用三个以上的-、*或_---注意-在 Markdown 里也表示无序列表单独一行写入---会被识别为分割线但如果你在前面紧跟着一段文字可能会被解析成二级标题。如果你发现分割线不见了、反而变成标题样式检查一下前面有没有空行隔开。HTML 混写是 Markdown 的隐藏大招。很多新手不知道Markdown 本身允许内嵌 HTML 标签所以你可以用br换行、用span stylecolor:red标红文字、甚至用details折叠块。这个特性在 Typora 和有不少在线编辑器中都能用。转义字符也很重要。如果你想显示一个真实的#开头但不被当成标题可以在前面加反斜杠\# 这不是标题 \*\*这不是加粗反斜杠的作用是让特殊字符恢复字面含义。记住这几个常用转义\#、\*、\、、[、]、.数字列表。3. 实操搭好写作环境写出第一份 Markdown 文档语法学得再多不实操都白搭。这一章我会带你从零搭好写作环境然后写一份完整的文档示例最后把它导出成你需要格式。3.1 编辑器选型我用过这三种各有利弊工欲善其事必先利其器。我用过的 Markdown 编辑器有七八种最后真正留下来的有三个。Typora所见即所得的代表写的时候直接看到排版效果没有任何干扰。它的最大优势是「沉浸感」打开就是一个空白画布你写什么得什么。缺点是它现在收费了我记得买断价不高而且有些快捷键对新手不够直观。如果你愿意花点小钱买写作体验Typora 非常值得。VS Code Markdown Preview Enhanced 插件免费、跨平台、可编程。VS Code 本身是代码编辑器但装了插件后 Markdown 体验相当不错可以自定义 CSS 样式、导出 PDF、甚至用 PlantUML 画图。缺点是默认界面重打开稍慢适合本身就常用 VS Code 的程序员。在线编辑器StackEdit、Dillinger 等零安装打开浏览器就能写。适合临时记笔记、快速转换格式但不适合长时间写长文刷新页面容易丢。如果你是纯新手我的建议是从 Typora 开始因为它上手门槛最低。等用熟了再根据自己需求扩展其他工具。3.2 安装 Typora 并完成三个关键设置安装我就不细说了官网下载按提示来就行。关键是安装完以后你要做三个设置否则体验会打折。设置一启用「自动保存」。Typora 默认是手动保存写长文时如果忘记保存崩溃就完蛋了。进入文件 - 偏好设置 - 通用勾选「自动保存」并设置间隔时间。设置二修改图片存储位置。进入偏好设置 - 图像插入图片时建议选择「复制图片到 ./images 文件夹」或「复制到指定路径」。这样你在文档里拖入截图Typora 会自动把图片文件复制到本地相对路径避免图片路径指向一个临时文件夹。设置三开启「Markdown 扩展语法」。在偏好设置 - Markdown里把能开的扩展都开了上标、下标、高亮、数学公式、任务列表。这样你用 Typora 写语法时不会被限制。3.3 手把手写一份完整的 Markdown 文档下面我演示一次完整的写作过程包含标题、表格、代码、引用、列表写完后你直接对照学习。假设我要写一份「部署说明文档」原始内容如下# 项目部署说明 最后更新2025-06-01 适用环境Linux / macOS ## 1. 环境要求 部署前请确认本机已安装以下软件 - Git 2.30 - Node.js 16 - npm 8 ## 2. 安装步骤 ### 2.1 拉取代码 bash git clone https://github.com/example/my-project.git cd my-project2.2 安装依赖npm install3. 配置说明配置项默认值说明port3000服务端口host0.0.0.0监听地址4. 常见问题如果端口被占用请修改config.js中的port字段。如果依赖安装失败请尝试清理 npm 缓存后再执行。这份文档里用到了标题、引用、列表、代码块、表格、行内代码、有序列表。你可以照着敲一遍感受一下 Markdown 的书写节奏。 ### 3.4 导出Markdown 转 HTML、PDF、Word 写完文档后最常见的需求是导出成其他格式。 - **导出 HTML**Typora 里 文件 - 导出 - HTML会生成一个 .html 文件双击用浏览器打开就是渲染后的效果。这个文件可以直接上传到任意 Web 服务器上部署不依赖 Markdown 环境。 - **导出 PDF**Typora 支持直接导出 PDF但要注意如果你的文档里含代码块和表格PDF 的换页可能不完美。我可以告诉你一个小技巧导出 PDF 前在 Markdown 里手动插入 - 分割线或者用 CSS 设置分页符。 - **导出 Word**Typora 导出 Word 依赖 Pandoc。安装 Pandoc 后执行 文件 - 导出 - Word 即可。但注意导出的 .docx 排版不是 100% 还原复杂表格和自定义 CSS 样式可能丢失。如果只是给同事看内容完全够用如果要精确排版还是得在 Word 里手动调。 如果你用的是 VS CodeMarkdown Preview Enhanced 插件支持右键导出 HTML、PDF、Word同样依赖 Pandoc。在线编辑器 StackEdit 也提供导出功能但不支持 PDF。 ### 3.5 进阶Markdown 转 Word 的自动化工作流 这个是我最近在折腾的方向。热搜词里有个「markdown转word工作流coze」其实思路就是用自动化工具把 .md 文件批量转成 .docx 或特定格式文档适用于需要频繁更新文档的团队。 我的做法是写一个脚本用 Pandoc 把 Markdown 转成 Word同时用 docx 模板控制样式。核心命令如下 bash pandoc input.md -o output.docx --reference-docreference.docxreference.docx是你预先设定好样式的 Word 模板标题字体、正文样式、页边距等。这样改的只是 Markdown 源码生成的 Word 会自动套用模板省掉了大量手动调格式的时间。如果还要彻底自动化可以把它挂到 Git 钩子里或 CI 流程中检测到 Markdown 文件变更时自动触发转换脚本。这在管理多份技术文档、说明书时尤其有用。4. 常见问题与排查技巧实录用 Markdown 写作时间长了总会遇到各种奇怪的问题。我把高频问题整理成了一份速查表你遇到类似情况可以直接按图索骥。4.1 问题速查表现象原因解决办法回车换行不生效Markdown 用空行分段落单个回车在部分解析器中不换行段落间加空行或行尾加两个空格 /br标题渲染成普通文字#后没加空格在#后加空格再写字表格复制到 Excel 变乱Typora 复制的是 HTML 格式Excel 解析行列逻辑不同源码模式复制粘贴到 Excel 后用「文本分列」或转 CSV图片本地能显示发到网上裂开使用了绝对路径改用相对路径图片与.md一起上传代码块出现奇怪的灰色底纹代码围栏没闭合或标注语言类型错误检查三个反引号是否成对标注正确语言分割线变成二级标题---前缺少空行在---前后加空行#无法正常显示被解析成标题语法使用\#转义列表嵌套时层级乱子列表缩进不足子列表统一缩进 2 或 4 个空格导出 PDF 时表格被截断PDF 分页导致表格跨页手动调整表格位置或改用导出 Word 再转 PDF在 GitHub 上某些语法不渲染GFM 扩展语法与编辑器不兼容写文档前确认目标平台的渲染规范4.2 Typora 打不开多个文件的解决办法热搜词里有一个高频问题「为什么我的 markdown 文件用 typora 打开每次只能打一个再打开一个没有反应」。这个我遇到过原因一般出在 Typora 的特性或文件关联上。先说结论Typora 默认设计就是单窗口模式。你打开第二个.md文件时它会把原来窗口的内容替换掉而不是新开一个窗口。如果你依赖多窗口对照阅读可在偏好设置文件 - 打开里勾选「以新窗口打开文件」相关选项具体名称不同版本可能不一样。如果勾选后仍然打不开第二个窗口试试看快捷键Ctrl N新建窗口再把需要的文件拖进去。还有一种可能是文件被其他程序占用比如 Word、WPS 打开了同一个文件Typora 无法获取文件锁表现为「点了没反应」。把其他程序关闭后重试即可。4.3 不同编辑器的兼容性差异Markdown 看起来简单但实际渲染时不同编辑器之间有明显差异。我亲自踩过的坑包括Typora 支持上标^text^和下标~text~但 GitHub 不支持。如果你在 Typora 里写了2^10^推到 GitHub 上可能变成2^10^原样显示。Typora 支持手写$$LaTeX$$数学公式但普通 Markdown 预览工具不一定渲染。任务列表- [x]在 GitHub 和 Typora 里都能正确渲染但有些在线编辑器把它当成普通列表。解决思路是先确定你的最终发布平台再以它的渲染规范为准。如果你要同时发布到公众号、知乎、GitHub建议只用 CommonMark 标准语法扩展语法少用。4.4 代码块符号导致的渲染异常有段时间我写技术笔记发现文档末尾总是莫名出现一大片灰色区域排查了半天才发现是代码块围栏没有闭合。当时我在文章里连续贴了两段代码第一段用三个反引号开头却忘了在末尾写结束的三个反引号导致渲染器把后面所有内容全当成了代码。这个问题的排查方法很简单在 Typora 里切到源码模式搜索反引号出现次数。正常情况下行内代码的反引号成对代码块的围栏反引号也成对。如果反引号总数是奇数肯定有地方漏了。另一个相关问题是如果你在代码块里写了三个反引号比如展示 Markdown 语法本身围栏会被提前截断。解决办法是用四个反引号作为外层围栏markdown 代码块里的代码 这样渲染后内层的三个反引号就会以普通文本形式显示出来。4.5 为什么我写的 Markdown 在手机预览器里错位移动端查看 Markdown 渲染效果时偶尔会出现表格错位、代码块溢出。多数原因是手机浏览器对复杂表格的解析宽度不足而不是 Markdown 语法错误。解决办法有几个一是表格列数控制在 5 列以内二是给表格行数少、内容短的内容加表头三是长代码块尽量手动换行避免超宽。如果你在手机上阅读别人的 Markdown 文档遇到错位大概率是对方没有考虑移动端适配而不是语法问题。4.6 Markdown 渲染成 HTML 时如何自定义样式前面提过 Markdown 最终会转成 HTML如果你对默认渲染样式不满意可以通过 CSS 覆盖。以 Typora 为例它支持自定义主题 CSS以 VS Code 的 Markdown Preview Enhanced 为例你可以在预览面板中注入自定义 CSS。我的做法是维护一份style.css给标题加颜色、给代码块加圆角、给表格加边框。这样导出 HTML 后直接把 CSS 文件一起发布页面效果会比默认样式好看很多。如果你开发自己的页面想用 Markdown 渲染成 HTML 嵌入网页可以借助前端库。常见的有 marked.js、markdown-it、remark它们提供了现成的解析函数。比如import { marked } from marked; const html marked.parse(# 标题); document.getElementById(content).innerHTML html;我自己在写小工具时用的是 markdown-it它的插件生态很丰富支持自定义渲染规则适合做高级定制。5. 从基础语法到写作效率我的几个习惯学完语法、踩完坑最后分享几个我写 Markdown 时的实操习惯。这些不是标准答案但都是实测下来能提升效率的做法。5.1 固定文档头让文章信息一目了然我开始认真写笔记后给每份.md文件都加了一个文档头YAML Front Matter 或表格形式包含标题、作者、创建日期、最后更新、标签、摘要。以 Typora 为例它天然支持 YAML Front Matter写格式如下--- title: Markdown 基础语法学习笔记 author: 某博主 date: 2025-06-01 tags: [Markdown, 笔记] ---加了文档头之后文件本身就有了一套元信息。导出 PDF 或 HTML 时主题会读取这些字段生成页面标题不用每次手动输入。5.2 用 Markdown 写笔记随时记录「为什么」很多新手写笔记只会抄标题和结论我吃了亏才改过来。Markdown 的核心优势是能快速标注「为什么」和「怎么做」所以我会用添加引用、列表、代码块的方式把每一步的意图写清楚。比如### 3.1 安装依赖 为什么先装依赖因为后续构建需要 node_modules 目录。 bash npm install这样三个月后回看这份笔记你还能想起来当时的决策原因而不是面对一堆命令发呆。 ### 5.3 反向利用 Markdown 渲染写博客、发公众号 我现在的公众号文章也是先写 Markdown再用工具转排版。虽然公众号编辑器本身不支持 Markdown但可以用「Markdown Here」这类浏览器插件把剪贴板里的 Markdown 一键渲染成富文本。你在编辑器里写好语法块一键转换后粘贴到公众号后台比手工调字号高效太多。 ### 5.4 团队协作时用 Markdown 要求你的队友 如果你在团队里维护文档可以约定所有输出内容统一使用 Markdown。好处是diff 的时候能看出文本级变化代码审查工具能正常解析不会出现「两个人同时编辑一个 Word 文档后一方覆盖另一方」的场景。Git 本身就擅长处理纯文本 diffMarkdown 搭上 Git天然适配协作。 ## 6. 写在最后Markdown 真的值得花时间学吗 这句是我的真心话非常值得。 Markdown 可能是目前投入产出比最高的文档技能学一遍基础语法大概只需半天但之后的每一次写作任务都会从中受益。你写技术文档、写博客、写课程笔记、写项目 README甚至写邮件只要有 Markdown 的地方这套技能就能迁移。 我个人在实际操作中的体会是Markdown 的真正门槛不在于语法本身而在于养成「结构先行」的写作习惯。当你开始用 # 规划文章大纲、用列表拆解逻辑、用表格整理对比信息时写作的思路会变得更清晰。这份学习笔记写到这儿我的建议是你现在就打开一个 .md 文件把今天学的基础语法挨个敲一遍遇到问题再回来看这张速查表应该很快就能上手。