最早我是不太信“一图秒懂”这种说法的尤其是碰上一个和代码沾边的东西。但Markdown是个例外我带着好几位完全零编程基础的朋友入了门从打开编辑器到写出第一篇带标题、列表、链接和图片的MD文档基本都用不了一顿饭的功夫。这个文件后缀 .md 的纯文本格式靠的不是复杂的操作界面而是一套简单到有些“朴素”的语法标签。你不需要记住几十个按钮在哪只需要像在文档里做记号一样用几个符号告诉电脑这里是标题那里要加粗这句话是引用。这种写作方式一旦习惯基本就回不去了。这篇内容就是给还没接触过、或者看了一堆复杂教程反而犯迷糊的人准备的也是一份我自己平时经常回看的速查笔记。1. Markdown到底解决了我写作时的什么痛点正经聊语法之前得先搞清楚一个问题为什么放着Word这种排版功能强大的工具不用偏要拿纯文本写东西1.1 写作和排版本来是两件事我参与写技术文档和博客这几年最深的感受是Word的排版功能确实强大但恰恰是这种强大让写作过程变得臃肿。写个标题要选中文字调字号调颜色调间距想在文档里加个代码片段还得专门弄个文本框然后祈祷复制粘贴的时候格式别乱。写作本身是思考的过程排版却是和格式工具斗争的过程两者搅在一起思路很容易断。Markdown的思路完全反过来写作的时候只管写内容。所有排版需求统统用语法标签在文本里标注出来。比如想在文档里加一个大标题就在这行字前面敲一个#和空格想加粗某句话就用两个星号把这句话包起来。这些标签在编辑的时候就是纯文本但经过渲染之后就会变成漂亮的标题和加粗文字。我比喻给朋友听用Word排版就像是把笔记写好之后还要誊抄一遍用Markdown则是你在草稿纸上写“这里空两格换一行写”别人一看就懂而且电脑可以瞬间帮你把这个“誊抄”过程完成。1.2 一个文件处处能用Markdown还有一个好处是几乎所有平台都认。我最早用Markdown是因为要在GitHub上写项目说明README后来发现写博客、写知识库、写邮件、在论坛发帖甚至做PPT都可以输出成Markdown或者在编辑器里直接用MD格式写作。这背后的逻辑有点像你用的充电线以前每个设备一个接口现在都统一成了Type-C。MD文件就是那个Type-C接口——它跨越了各种笔记软件、代码托管平台、博客系统和文档工具。今天你在VS Code里写一个MD文件明天放到语雀、Obsidian、Notion、知乎或者自己的博客后台内容结构基本不会乱。这在“内容搬来搬去”的场景里太省心了。1.3 Markdown、Word、HTML到底什么关系简单列个对比对比维度MarkdownMDWord文档HTML核心文件纯文本 .md 文件二进制 .docx 文件文本 .html 文件操作方式写语法标签实时或事后渲染菜单按钮鼠标操作写完整带尖括号的标签学习成本低半小时够用低但不精排版需要长期磨合较高需要理解层级与属性跨平台性极好到处通用一般依赖Office软件与版本好浏览器全支持适合场景笔记、文档、博客、说明正式印刷、复杂排版、商务文件网页开发这里要说清楚Markdown并不是要替代Word或者HTML。Word在复杂排版、批注协作、正式公文场景下仍然有不可替代的地位HTML则是网页世界的底层语言。Markdown更像是介于两者之间的“轻量级标记语言”它用最少的符号覆盖了日常写作里80%以上的排版需求剩下的复杂版式需求一般通过嵌入HTML标签也能实现。所以我不觉得它是“降级”更像是一种更纯粹的写作方式。2. 一张速查表看懂高频语法标签这部分就是标题里说的“一图秒懂”。我不会把所有冷门语法都堆给你只挑日常写作里出现频率最高的那些。Markdown核心语法其实就那么十几组我当初整理在便签里随身看几天之后就全记住了。2.1 标题井号的数量决定层级Markdown标题用#来表示数量从1到6对应六级标题# 这是一级标题 ## 这是二级标题 ### 这是三级标题 #### 这是四级标题 ##### 这是五级标题 ###### 这是六级标题注意#和文字之间要留一个空格这是很多新手栽跟头的地方。不空格也能渲染但兼容性不好换到某些平台可能就失效了。标题层级的设计逻辑和Word里的“标题1”“标题2”是一样的方便生成目录、定位文档结构。2.2 核心语法速查总表下面这张表就是我日常使用频率最高的语法我建议你先用这张表练习其他的以后碰到了再查细节功能语法写法效果加粗**加粗文字**加粗文字斜体*斜体文字*斜体文字删除线~~删除内容~~~~删除内容~~行内代码codecode无序列表- 项目或* 项目项目列表有序列表1. 第一项编号列表引用 引用内容缩进引用链接[显示文字](网址)可点击链接图片显示图片分割线---横向分隔线行内代码块用反引号包裹等宽字体效果代码块三个反引号包裹带格式代码区域2.3 用一段示例串起所有标签光看表格容易迷糊我习惯让朋友上手敲一段“语法全家桶”把常用标签一次性试一遍# 周末爬山计划 周六早上 **8点** 在公园南门集合_过时不候_。这次任务分三组 - 第一组采购水和干粮 - 第二组检查登山设备 - 第三组提前探路 注意天气预报说下午有雨~~山顶烧烤环节~~ 取消。 导航到集合点[公园位置](https://example.com/map)  --- 如有问题联系我zhangsanexample.com python print(记得带雨衣)这串内容渲染出来就是一篇结构分明的文档有标题、有列表、有引用、有链接、有图片、有分割线、有行内代码和代码块。当你亲手把这些标签敲一遍再看到渲染效果基本就算入门了。 ## 3. 换行、图片路径、表格对齐新手最容易卡住的四个细节 语法速查表大家都看得懂但真正开始写的时候踩坑的点往往不是那些常用标签而是一些“貌似很简单、实际有坑”的细节。这几个坑我几乎在每个人身上都见过也包括当年的自己。 ### 3.1 换行到底按一下还是两下回车 这个坑出现的频率高得离谱。很多人写完一行字按一次回车结果渲染出来发现和上一行是连在一起的。原因在于Markdown里的换行规则和普通文本编辑器不太一样 - 单个回车在大部分Markdown编辑器里不会产生新段落只相当于一个空格 - 要实现真正的换行需要在一行结尾敲两个空格然后再回车 - 更推荐的做法是直接空一行——也就是按两次回车这样会生成一个新的段落。 我来演示一下区别。下面这段源码 markdown 第一行 第二行上面行尾有两个空格 第三行这是另一个段落渲染出来的效果就是第一行和第二行虽然在不同行但属于同一段落间距很小第三行则和前两行有明显的段落间距。所以如果你发现自己的MD文档里换行不生效先检查行尾有没有两个空格或者是否空了一行。这与在Markdown里敲出一段段结构清晰的文字直接相关。3.2 图片路径本地图片和网络图片是两回事图片标签看起来简单但这个“路径”里坑不少。先说结论如果路径是以http://或https://开头那就是网络图片任何人打开这个MD文件只要能联网就能看到图如果路径是本地文件比如那只有你这一台电脑上的文件路径有效换个设备、发给别人、传到博客后台图片大概率挂掉相对路径比如意思是“当前文件所在目录下的img文件夹里的1.png”这在本地项目里很常用比如GitHub仓库里放图片。讲个具体场景你写了篇带截图的技术博客图片存在笔记本电脑的桌面上整个文件复制到另一台电脑图片路径变了渲染时就变成裂图。正确做法是在项目目录下建一个images文件夹把所有图片放进去然后用相对路径引用如果是要发到网上的内容先把图片传到图床或对象存储再用网络URL引用。这也是为什么很多人用过Typora之后会把图片存储方式设置成“复制到指定文件夹”或者“上传图片”本质都是在解决路径失效的问题。3.3 表格对齐不是对齐是冒号的位置Markdown表格语法看起来有点奇怪但它其实是后端HTML表格的简化写法。基础结构长这样| 项目 | 价格 | 数量 | | ---- | ---- | ---- | | 苹果 | 5元 | 3斤 | | 香蕉 | 3元 | 5斤 |渲染出来就是一个标准表格。如果你想让某一列的文字居中、左对齐或右对齐靠的是分隔行里冒号的位置| 默认左对齐 | 居中对齐 | 右对齐 | | ---------- | :------: | -----: | | 内容A | 内容B | 内容C |注意冒号在两边就是居中在右边就是右对齐光写横杠就是左对齐其实是默认。这个细节很适合做参数对照或列数据展示时用。实际使用中最常见的问题是表格单元格里如果出现竖线|需要转义成\|不然表格会断掉。可能你会问在VSCode、Obsidian这类编辑器里写表格手动敲竖线太累了。这个问题等下面聊工具的时候一起说有插件能自动格式化。3.4 代码块的语法高亮语言名要标对代码块最常见的写法是三反引号加语言名python print(hello) 这个python就是语言标识编辑器会根据它来做高亮。很多人写代码块时只写了三个反引号不起新行或者不标语言能正常显示但缺乏高亮对于代码阅读来说体验差很多。常见的语言标识包括python、javascript、bash、java、cpp、sql、json、html、css等。还有一个容易踩的坑是嵌套代码块如果你要在代码块里展示代码块的写法内层需要用比外层多一个的反引号包裹。比如你写博客要教别人“怎么写代码块”外层用了三个反引号内层你就得用四个反引号这样渲染时才不会提前闭合。4. 语法符号背后的设计逻辑理解了就不用死记有一类教程让人痛苦就是把语法整理成几十条让人像背单词一样记。实际上Markdown的语法设计是有规律的理解了它“为什么这么设计”至少一半的语法不需要刻意背。4.1 标记语言的核心思路符号是给内容的“格式批注”Markdown所有语法的底层逻辑都是同一个在纯文本里插入一些特殊符号这些符号本身不参与内容输出只负责告诉渲染程序“这段内容应该以什么格式展示”。比如**文字**里的两个星号并不是内容的一部分它们只是格式指令。用生活化的例子来想你在纸质稿子上批注“这行加粗”Markdown文本里的**就扮演着这个批注的角色。只不过它用的是统一的符号不用写字说明渲染程序一看就懂。这也就解释了为什么Markdown文件本身是可读的——哪怕不渲染你看到的也只是带了符号的普通文字内容照样清清楚楚。这比起HTML那种满屏尖括号标签可直观多了。4.2 块级元素与行内元素是理解语法的两扇门Markdown里的语法表面上很多实际可以分为两大类。理解这个分类比记住某个符号更接近本质块级元素作用于整块内容比如标题、段落、列表、引用、代码块、表格。它们通常独占一块区域开头有特定的符号如#、、-并且后面要跟一个空格再写内容行内元素作用于某一行中的局部文字比如加粗、斜体、行内代码、链接。它们是成对出现的包裹符把需要特殊格式的文字包在中间。用代码来对照看一下。下面源码里的-是块级符号它让“苹果”成为列表项**则是行内符号它让“好吃”变成加粗- 苹果**好吃** - 香蕉也不错搞清了这两个分类你就能预测凡是需要“单独占一行”的格式大概率是行首加符号后面接空格凡是需要“影响部分文字”的格式大概率是成对包裹。这好比整理房间先分“大件家具”和“桌上小物件”两个区再讨论怎么摆思路就顺了。4.3 嵌套和转义保持简单中的灵活Markdown简单但遇到复杂排版时怎么办两条路一是嵌套二是转义。嵌套就是把一个语法放进另一个语法里。典型的例子是列表里再套列表- 水果 - 苹果 - 香蕉 - 饮料 1. 可乐 2. 橙汁子级列表需要缩进两个或四个空格渲染出来就是多级嵌套结构。还有引用块里放代码块、表格里放链接也都是嵌套的常见用法。遇到特殊情况比如要在文档里显示*号本身不想触发斜体就在前面加一个反斜杠\*这个操作叫转义。它和编程语言里的转义思路一致逻辑是“让下一个字符按原样显示”。所以碰到“Markdown里怎么显示星号”“怎么写井号不变标题”之类的问题不需要死记想想转义这个规则就解决了。5. 编辑器与工具链从Typora到VSCode再到跨格式转换语法本身学起来快真正影响日常体验的是编辑器。每个工具都有自己的脾气我聊几个最常见的选择以及它们适合谁。5.1 编辑器选择其实是在选渲染反馈方式Markdown编辑器大致分两派所见即所得派和源码实时预览派。没有绝对好坏只看你平时写作的习惯。我用过的编辑器里目前主流的几款各自特征如下编辑器风格适合场景注意点Typora所见即所得隐藏语法标记新手写作、博客文章收费软件购买前可以先试用VS Code源码编辑侧边预览开发者、技术文档上手有门槛搭配插件后功能全面Obsidian所见即所得与源码结合本地知识库、个人笔记文件放在本地支持双链Jupyter NotebookMarkdown单元格实时渲染数据分析、教学演示适合穿插代码与说明文字语雀/Notion平台内编辑器在线协作、团队文档数据和平台绑定较紧密5.2 VS Code写Markdown可以这样配置说个最常被问的组合——用VS Code编辑Markdown。VS Code本身是代码编辑器但配上插件之后写MD文档的体验不输专业编辑器。我自己的配置是编辑器自带Markdown预览按下CtrlShiftVMac上是CmdShiftV可以在右侧直接打开预览CtrlK V则是分屏预览安装“Markdown All in One”插件自动完成表格格式化、目录生成、列表自动补全、路径补全等功能。写表格时它会自动对齐竖线让源码看起来整整齐齐安装“Markdown Preview Enhanced”插件增强预览效果支持导出PDF、HTML还支持画流程图、甘特图、公式渲染适合把MD文档当成完整的排版工具使用如果你需要画流程图部分增强预览插件支持用mermaid语法描述流程不是用图片而是用文本生成图形写技术方案特别方便。对于不熟悉VS Code的人来说第一次打开会有点“功能太多”的压迫感。其实你用Markdown只需要把文件管理器、编辑区、预览区打开其他面板全部关掉体验就很干净了。5.3 格式转换md和其他格式互转是内容流动的关键Markdown的跨平台优势还体现在格式转换上。这里最值得提的是 Pandoc一套命令行转换工具堪称“文档格式转换瑞士军刀”。它可以把Markdown转成Worddocx、PDF、HTML、LaTeX、EPUB等几十种格式也能把一些格式转回Markdown。举例我想把一个MD文件转成Word发给同事一条命令搞定pandoc input.md -o output.docx如果你想从PDF、网页或者Word里提取内容变成Markdown也有两条路一是用Pandoc配合特定参数比如pandoc input.docx -t markdown -o output.md效果取决于原文档结构是否规整二是在线转换工具或者一些专门把网页内容“剪藏”成Markdown的浏览器插件。现在不少开源项目还在GitHub上维护这类“任意格式转Markdown”的工具比如对PDF抽取结构再转成MD的流程已经做得比较成熟。这个“强转换能力”是我推荐大家把笔记沉淀成Markdown的重要原因之一你的内容不会被困在某一个软件里。今天你用的笔记软件凉了或者你换工作了要交接全部文档MD文件依然是那个最通用、最不会过期的格式。6. 进阶方向表格、数学公式、目录跳转和我的几个习惯基础语法聊完了工具也选好了最后再分享一些使用中的进阶内容和我的个人习惯。这些内容不一定入门第一天就用到但知道了会让后续使用顺畅不少。6.1 数学公式Markdown里的LaTeX语法做技术笔记、写论文或学习记录经常需要写数学公式。Markdown本身不带公式功能但很多编辑器内置了LaTeX公式渲染能力通用写法是用美元符号$包裹行内公式$Emc^2$ 独立公式 $$ \frac{-b \pm \sqrt{b^2-4ac}}{2a} $$具体支持情况因编辑器而异。Typora、Obsidian、VS Code的Markdown增强预览、语雀等都支持GitHub网页版渲染仓库里的公式也没问题。建议在正式用之前拿自己的编辑器试一下别到写笔记时才发现公式不渲染。这也是我在前面强调“工具选型影响体验”的原因之一。6.2 目录生成与锚点跳转文档一长目录就很重要。很多Markdown编辑器能根据#标题自动生成侧边栏或目录。比如Typora和VS Code的插件都有“大纲”面板Obsidian左侧也可以展开大纲视图。如果要在文档里插入目录常见写法是[TOC]或使用Markdown All in One插件生成目录列表。具体语法取决于编辑器支持情况但底层原理都是同一个利用标题作为锚点实现文档内跳转。所谓锚点就是文档里每个标题会自动生成一个跳转位置你可以写[跳转到第一节](#1-第一节)这样的链接点击后直接滚动到对应标题。熟悉了这个概念写长文档的时候就不用反复滚动鼠标了。6.3 Obsidian里的块折叠其实是MD扩展语法有人问Obsidian里Markdown格式块能不能折叠这个功能是Obsidian基于标准Markdown做的扩展。语法是 [!note] 这段可以折叠 这里是详细内容或者用HTML的details标签实现。这类属于“编辑器私有语法”换一个软件可能不生效。我的建议是基础内容用标准Markdown写保证可移植性需要交互效果时再用编辑器特定语法但要心里清楚“换平台可能会失效”。6.4 我沉淀下来的几条使用习惯第一文件命名和图片文件夹从第一天就规范。我所有笔记项目都是项目名.md加一个assets或images文件夹图片统一放进去用相对路径引用。看起来多花了几秒但半年后回来看文档没有碎图谁接手都能看懂。第二标题层级要保持一致。我在写长文档时会先用一轮大纲把#到###的层级列好然后才开始填内容。这样自动生成的目录一定清晰后续调整结构也比边写边乱切标题省力得多。第三重视快捷键。Markdown不需要记太多快捷键但几个高频操作值得练习预览切换、代码块插入、加粗文字。说个实际例子用VS Code写MD时选中文字后按CtrlB可以直接加粗效率比手输两个星号高得多。第四commit或备份时把MD文件当文本处理就好。MD文件小、可读、方便版本管理这也是为什么很多开源项目选择用Markdown维护文档。哪怕你只是个人写笔记用Git或网盘定期备份都很轻量。这些习惯看着微不足道但恰恰是它们决定了Markdown工具链能不能真正沉淀成自己的知识管理体系。工具是公共的语法是通用的差异就在细节里。 Markdown语法速查：从入门到高效写作的完整指南
最早我是不太信“一图秒懂”这种说法的尤其是碰上一个和代码沾边的东西。但Markdown是个例外我带着好几位完全零编程基础的朋友入了门从打开编辑器到写出第一篇带标题、列表、链接和图片的MD文档基本都用不了一顿饭的功夫。这个文件后缀 .md 的纯文本格式靠的不是复杂的操作界面而是一套简单到有些“朴素”的语法标签。你不需要记住几十个按钮在哪只需要像在文档里做记号一样用几个符号告诉电脑这里是标题那里要加粗这句话是引用。这种写作方式一旦习惯基本就回不去了。这篇内容就是给还没接触过、或者看了一堆复杂教程反而犯迷糊的人准备的也是一份我自己平时经常回看的速查笔记。1. Markdown到底解决了我写作时的什么痛点正经聊语法之前得先搞清楚一个问题为什么放着Word这种排版功能强大的工具不用偏要拿纯文本写东西1.1 写作和排版本来是两件事我参与写技术文档和博客这几年最深的感受是Word的排版功能确实强大但恰恰是这种强大让写作过程变得臃肿。写个标题要选中文字调字号调颜色调间距想在文档里加个代码片段还得专门弄个文本框然后祈祷复制粘贴的时候格式别乱。写作本身是思考的过程排版却是和格式工具斗争的过程两者搅在一起思路很容易断。Markdown的思路完全反过来写作的时候只管写内容。所有排版需求统统用语法标签在文本里标注出来。比如想在文档里加一个大标题就在这行字前面敲一个#和空格想加粗某句话就用两个星号把这句话包起来。这些标签在编辑的时候就是纯文本但经过渲染之后就会变成漂亮的标题和加粗文字。我比喻给朋友听用Word排版就像是把笔记写好之后还要誊抄一遍用Markdown则是你在草稿纸上写“这里空两格换一行写”别人一看就懂而且电脑可以瞬间帮你把这个“誊抄”过程完成。1.2 一个文件处处能用Markdown还有一个好处是几乎所有平台都认。我最早用Markdown是因为要在GitHub上写项目说明README后来发现写博客、写知识库、写邮件、在论坛发帖甚至做PPT都可以输出成Markdown或者在编辑器里直接用MD格式写作。这背后的逻辑有点像你用的充电线以前每个设备一个接口现在都统一成了Type-C。MD文件就是那个Type-C接口——它跨越了各种笔记软件、代码托管平台、博客系统和文档工具。今天你在VS Code里写一个MD文件明天放到语雀、Obsidian、Notion、知乎或者自己的博客后台内容结构基本不会乱。这在“内容搬来搬去”的场景里太省心了。1.3 Markdown、Word、HTML到底什么关系简单列个对比对比维度MarkdownMDWord文档HTML核心文件纯文本 .md 文件二进制 .docx 文件文本 .html 文件操作方式写语法标签实时或事后渲染菜单按钮鼠标操作写完整带尖括号的标签学习成本低半小时够用低但不精排版需要长期磨合较高需要理解层级与属性跨平台性极好到处通用一般依赖Office软件与版本好浏览器全支持适合场景笔记、文档、博客、说明正式印刷、复杂排版、商务文件网页开发这里要说清楚Markdown并不是要替代Word或者HTML。Word在复杂排版、批注协作、正式公文场景下仍然有不可替代的地位HTML则是网页世界的底层语言。Markdown更像是介于两者之间的“轻量级标记语言”它用最少的符号覆盖了日常写作里80%以上的排版需求剩下的复杂版式需求一般通过嵌入HTML标签也能实现。所以我不觉得它是“降级”更像是一种更纯粹的写作方式。2. 一张速查表看懂高频语法标签这部分就是标题里说的“一图秒懂”。我不会把所有冷门语法都堆给你只挑日常写作里出现频率最高的那些。Markdown核心语法其实就那么十几组我当初整理在便签里随身看几天之后就全记住了。2.1 标题井号的数量决定层级Markdown标题用#来表示数量从1到6对应六级标题# 这是一级标题 ## 这是二级标题 ### 这是三级标题 #### 这是四级标题 ##### 这是五级标题 ###### 这是六级标题注意#和文字之间要留一个空格这是很多新手栽跟头的地方。不空格也能渲染但兼容性不好换到某些平台可能就失效了。标题层级的设计逻辑和Word里的“标题1”“标题2”是一样的方便生成目录、定位文档结构。2.2 核心语法速查总表下面这张表就是我日常使用频率最高的语法我建议你先用这张表练习其他的以后碰到了再查细节功能语法写法效果加粗**加粗文字**加粗文字斜体*斜体文字*斜体文字删除线~~删除内容~~~~删除内容~~行内代码codecode无序列表- 项目或* 项目项目列表有序列表1. 第一项编号列表引用 引用内容缩进引用链接[显示文字](网址)可点击链接图片显示图片分割线---横向分隔线行内代码块用反引号包裹等宽字体效果代码块三个反引号包裹带格式代码区域2.3 用一段示例串起所有标签光看表格容易迷糊我习惯让朋友上手敲一段“语法全家桶”把常用标签一次性试一遍# 周末爬山计划 周六早上 **8点** 在公园南门集合_过时不候_。这次任务分三组 - 第一组采购水和干粮 - 第二组检查登山设备 - 第三组提前探路 注意天气预报说下午有雨~~山顶烧烤环节~~ 取消。 导航到集合点[公园位置](https://example.com/map)  --- 如有问题联系我zhangsanexample.com python print(记得带雨衣)这串内容渲染出来就是一篇结构分明的文档有标题、有列表、有引用、有链接、有图片、有分割线、有行内代码和代码块。当你亲手把这些标签敲一遍再看到渲染效果基本就算入门了。 ## 3. 换行、图片路径、表格对齐新手最容易卡住的四个细节 语法速查表大家都看得懂但真正开始写的时候踩坑的点往往不是那些常用标签而是一些“貌似很简单、实际有坑”的细节。这几个坑我几乎在每个人身上都见过也包括当年的自己。 ### 3.1 换行到底按一下还是两下回车 这个坑出现的频率高得离谱。很多人写完一行字按一次回车结果渲染出来发现和上一行是连在一起的。原因在于Markdown里的换行规则和普通文本编辑器不太一样 - 单个回车在大部分Markdown编辑器里不会产生新段落只相当于一个空格 - 要实现真正的换行需要在一行结尾敲两个空格然后再回车 - 更推荐的做法是直接空一行——也就是按两次回车这样会生成一个新的段落。 我来演示一下区别。下面这段源码 markdown 第一行 第二行上面行尾有两个空格 第三行这是另一个段落渲染出来的效果就是第一行和第二行虽然在不同行但属于同一段落间距很小第三行则和前两行有明显的段落间距。所以如果你发现自己的MD文档里换行不生效先检查行尾有没有两个空格或者是否空了一行。这与在Markdown里敲出一段段结构清晰的文字直接相关。3.2 图片路径本地图片和网络图片是两回事图片标签看起来简单但这个“路径”里坑不少。先说结论如果路径是以http://或https://开头那就是网络图片任何人打开这个MD文件只要能联网就能看到图如果路径是本地文件比如那只有你这一台电脑上的文件路径有效换个设备、发给别人、传到博客后台图片大概率挂掉相对路径比如意思是“当前文件所在目录下的img文件夹里的1.png”这在本地项目里很常用比如GitHub仓库里放图片。讲个具体场景你写了篇带截图的技术博客图片存在笔记本电脑的桌面上整个文件复制到另一台电脑图片路径变了渲染时就变成裂图。正确做法是在项目目录下建一个images文件夹把所有图片放进去然后用相对路径引用如果是要发到网上的内容先把图片传到图床或对象存储再用网络URL引用。这也是为什么很多人用过Typora之后会把图片存储方式设置成“复制到指定文件夹”或者“上传图片”本质都是在解决路径失效的问题。3.3 表格对齐不是对齐是冒号的位置Markdown表格语法看起来有点奇怪但它其实是后端HTML表格的简化写法。基础结构长这样| 项目 | 价格 | 数量 | | ---- | ---- | ---- | | 苹果 | 5元 | 3斤 | | 香蕉 | 3元 | 5斤 |渲染出来就是一个标准表格。如果你想让某一列的文字居中、左对齐或右对齐靠的是分隔行里冒号的位置| 默认左对齐 | 居中对齐 | 右对齐 | | ---------- | :------: | -----: | | 内容A | 内容B | 内容C |注意冒号在两边就是居中在右边就是右对齐光写横杠就是左对齐其实是默认。这个细节很适合做参数对照或列数据展示时用。实际使用中最常见的问题是表格单元格里如果出现竖线|需要转义成\|不然表格会断掉。可能你会问在VSCode、Obsidian这类编辑器里写表格手动敲竖线太累了。这个问题等下面聊工具的时候一起说有插件能自动格式化。3.4 代码块的语法高亮语言名要标对代码块最常见的写法是三反引号加语言名python print(hello) 这个python就是语言标识编辑器会根据它来做高亮。很多人写代码块时只写了三个反引号不起新行或者不标语言能正常显示但缺乏高亮对于代码阅读来说体验差很多。常见的语言标识包括python、javascript、bash、java、cpp、sql、json、html、css等。还有一个容易踩的坑是嵌套代码块如果你要在代码块里展示代码块的写法内层需要用比外层多一个的反引号包裹。比如你写博客要教别人“怎么写代码块”外层用了三个反引号内层你就得用四个反引号这样渲染时才不会提前闭合。4. 语法符号背后的设计逻辑理解了就不用死记有一类教程让人痛苦就是把语法整理成几十条让人像背单词一样记。实际上Markdown的语法设计是有规律的理解了它“为什么这么设计”至少一半的语法不需要刻意背。4.1 标记语言的核心思路符号是给内容的“格式批注”Markdown所有语法的底层逻辑都是同一个在纯文本里插入一些特殊符号这些符号本身不参与内容输出只负责告诉渲染程序“这段内容应该以什么格式展示”。比如**文字**里的两个星号并不是内容的一部分它们只是格式指令。用生活化的例子来想你在纸质稿子上批注“这行加粗”Markdown文本里的**就扮演着这个批注的角色。只不过它用的是统一的符号不用写字说明渲染程序一看就懂。这也就解释了为什么Markdown文件本身是可读的——哪怕不渲染你看到的也只是带了符号的普通文字内容照样清清楚楚。这比起HTML那种满屏尖括号标签可直观多了。4.2 块级元素与行内元素是理解语法的两扇门Markdown里的语法表面上很多实际可以分为两大类。理解这个分类比记住某个符号更接近本质块级元素作用于整块内容比如标题、段落、列表、引用、代码块、表格。它们通常独占一块区域开头有特定的符号如#、、-并且后面要跟一个空格再写内容行内元素作用于某一行中的局部文字比如加粗、斜体、行内代码、链接。它们是成对出现的包裹符把需要特殊格式的文字包在中间。用代码来对照看一下。下面源码里的-是块级符号它让“苹果”成为列表项**则是行内符号它让“好吃”变成加粗- 苹果**好吃** - 香蕉也不错搞清了这两个分类你就能预测凡是需要“单独占一行”的格式大概率是行首加符号后面接空格凡是需要“影响部分文字”的格式大概率是成对包裹。这好比整理房间先分“大件家具”和“桌上小物件”两个区再讨论怎么摆思路就顺了。4.3 嵌套和转义保持简单中的灵活Markdown简单但遇到复杂排版时怎么办两条路一是嵌套二是转义。嵌套就是把一个语法放进另一个语法里。典型的例子是列表里再套列表- 水果 - 苹果 - 香蕉 - 饮料 1. 可乐 2. 橙汁子级列表需要缩进两个或四个空格渲染出来就是多级嵌套结构。还有引用块里放代码块、表格里放链接也都是嵌套的常见用法。遇到特殊情况比如要在文档里显示*号本身不想触发斜体就在前面加一个反斜杠\*这个操作叫转义。它和编程语言里的转义思路一致逻辑是“让下一个字符按原样显示”。所以碰到“Markdown里怎么显示星号”“怎么写井号不变标题”之类的问题不需要死记想想转义这个规则就解决了。5. 编辑器与工具链从Typora到VSCode再到跨格式转换语法本身学起来快真正影响日常体验的是编辑器。每个工具都有自己的脾气我聊几个最常见的选择以及它们适合谁。5.1 编辑器选择其实是在选渲染反馈方式Markdown编辑器大致分两派所见即所得派和源码实时预览派。没有绝对好坏只看你平时写作的习惯。我用过的编辑器里目前主流的几款各自特征如下编辑器风格适合场景注意点Typora所见即所得隐藏语法标记新手写作、博客文章收费软件购买前可以先试用VS Code源码编辑侧边预览开发者、技术文档上手有门槛搭配插件后功能全面Obsidian所见即所得与源码结合本地知识库、个人笔记文件放在本地支持双链Jupyter NotebookMarkdown单元格实时渲染数据分析、教学演示适合穿插代码与说明文字语雀/Notion平台内编辑器在线协作、团队文档数据和平台绑定较紧密5.2 VS Code写Markdown可以这样配置说个最常被问的组合——用VS Code编辑Markdown。VS Code本身是代码编辑器但配上插件之后写MD文档的体验不输专业编辑器。我自己的配置是编辑器自带Markdown预览按下CtrlShiftVMac上是CmdShiftV可以在右侧直接打开预览CtrlK V则是分屏预览安装“Markdown All in One”插件自动完成表格格式化、目录生成、列表自动补全、路径补全等功能。写表格时它会自动对齐竖线让源码看起来整整齐齐安装“Markdown Preview Enhanced”插件增强预览效果支持导出PDF、HTML还支持画流程图、甘特图、公式渲染适合把MD文档当成完整的排版工具使用如果你需要画流程图部分增强预览插件支持用mermaid语法描述流程不是用图片而是用文本生成图形写技术方案特别方便。对于不熟悉VS Code的人来说第一次打开会有点“功能太多”的压迫感。其实你用Markdown只需要把文件管理器、编辑区、预览区打开其他面板全部关掉体验就很干净了。5.3 格式转换md和其他格式互转是内容流动的关键Markdown的跨平台优势还体现在格式转换上。这里最值得提的是 Pandoc一套命令行转换工具堪称“文档格式转换瑞士军刀”。它可以把Markdown转成Worddocx、PDF、HTML、LaTeX、EPUB等几十种格式也能把一些格式转回Markdown。举例我想把一个MD文件转成Word发给同事一条命令搞定pandoc input.md -o output.docx如果你想从PDF、网页或者Word里提取内容变成Markdown也有两条路一是用Pandoc配合特定参数比如pandoc input.docx -t markdown -o output.md效果取决于原文档结构是否规整二是在线转换工具或者一些专门把网页内容“剪藏”成Markdown的浏览器插件。现在不少开源项目还在GitHub上维护这类“任意格式转Markdown”的工具比如对PDF抽取结构再转成MD的流程已经做得比较成熟。这个“强转换能力”是我推荐大家把笔记沉淀成Markdown的重要原因之一你的内容不会被困在某一个软件里。今天你用的笔记软件凉了或者你换工作了要交接全部文档MD文件依然是那个最通用、最不会过期的格式。6. 进阶方向表格、数学公式、目录跳转和我的几个习惯基础语法聊完了工具也选好了最后再分享一些使用中的进阶内容和我的个人习惯。这些内容不一定入门第一天就用到但知道了会让后续使用顺畅不少。6.1 数学公式Markdown里的LaTeX语法做技术笔记、写论文或学习记录经常需要写数学公式。Markdown本身不带公式功能但很多编辑器内置了LaTeX公式渲染能力通用写法是用美元符号$包裹行内公式$Emc^2$ 独立公式 $$ \frac{-b \pm \sqrt{b^2-4ac}}{2a} $$具体支持情况因编辑器而异。Typora、Obsidian、VS Code的Markdown增强预览、语雀等都支持GitHub网页版渲染仓库里的公式也没问题。建议在正式用之前拿自己的编辑器试一下别到写笔记时才发现公式不渲染。这也是我在前面强调“工具选型影响体验”的原因之一。6.2 目录生成与锚点跳转文档一长目录就很重要。很多Markdown编辑器能根据#标题自动生成侧边栏或目录。比如Typora和VS Code的插件都有“大纲”面板Obsidian左侧也可以展开大纲视图。如果要在文档里插入目录常见写法是[TOC]或使用Markdown All in One插件生成目录列表。具体语法取决于编辑器支持情况但底层原理都是同一个利用标题作为锚点实现文档内跳转。所谓锚点就是文档里每个标题会自动生成一个跳转位置你可以写[跳转到第一节](#1-第一节)这样的链接点击后直接滚动到对应标题。熟悉了这个概念写长文档的时候就不用反复滚动鼠标了。6.3 Obsidian里的块折叠其实是MD扩展语法有人问Obsidian里Markdown格式块能不能折叠这个功能是Obsidian基于标准Markdown做的扩展。语法是 [!note] 这段可以折叠 这里是详细内容或者用HTML的details标签实现。这类属于“编辑器私有语法”换一个软件可能不生效。我的建议是基础内容用标准Markdown写保证可移植性需要交互效果时再用编辑器特定语法但要心里清楚“换平台可能会失效”。6.4 我沉淀下来的几条使用习惯第一文件命名和图片文件夹从第一天就规范。我所有笔记项目都是项目名.md加一个assets或images文件夹图片统一放进去用相对路径引用。看起来多花了几秒但半年后回来看文档没有碎图谁接手都能看懂。第二标题层级要保持一致。我在写长文档时会先用一轮大纲把#到###的层级列好然后才开始填内容。这样自动生成的目录一定清晰后续调整结构也比边写边乱切标题省力得多。第三重视快捷键。Markdown不需要记太多快捷键但几个高频操作值得练习预览切换、代码块插入、加粗文字。说个实际例子用VS Code写MD时选中文字后按CtrlB可以直接加粗效率比手输两个星号高得多。第四commit或备份时把MD文件当文本处理就好。MD文件小、可读、方便版本管理这也是为什么很多开源项目选择用Markdown维护文档。哪怕你只是个人写笔记用Git或网盘定期备份都很轻量。这些习惯看着微不足道但恰恰是它们决定了Markdown工具链能不能真正沉淀成自己的知识管理体系。工具是公共的语法是通用的差异就在细节里。