有人说markdown难有人觉得markdown就是记笔记时偶尔用一下的语法还有人打开语法手册看两行就关掉了。但实际上大部分人对markdown的误解来源于没见过一张真正有用的速查图也没人告诉他你只需要记住这些剩下的边用边查。这篇内容就是把markdown最核心、最高频的语法标签一次性讲清楚并且把那些在手册里写得云里雾里的细节——比如换行、图片路径、表格、数学公式、工具链——全部摊开揉碎放到真实的使用场景里去解释。这篇文章适合谁看想用markdown做笔记、写技术文档、搭个人博客、做知识管理的人还有那些在vscode、typora、obsidian里写了半天却总在语法上卡壳的新手。我先说结论markdown完整规范有一百多处细节但你在实际写作里用到的不会超过20个标签。把这20个记住就已经超过市面上90%的日常使用者了。下面直接进入正题。1. 为什么markdown值得花半小时学会1.1 markdown解决的是写作被格式打断的问题先聊一个最根本的问题我们过去写文档用Word写完标题要选中文字、改字号、加粗、调行距一套操作下来思路早就断了。markdown的逻辑完全不同它把格式符号直接混在文字里你写# 标题就是一级标题写**加粗**就是加粗写完了不用拿鼠标反复去点工具栏手指不离开键盘思路不断。这个区别往深了说是所见即所得和所见即所写两个流派的分歧。Word是前者markdown是后者。但markdown的聪明之处在于它能在你写完的瞬间通过预览窗口渲染成带格式的样子等于鱼和熊掌兼得了。所以现在程序员写README、写技术文档产品经理写PRD博主写公众号草稿都在往markdown上迁。1.2 一次编写、到处渲染才是markdown最大的隐藏价值markdown文件本质是纯文本这就带来一个杀手级特性它不受任何软件绑架。你用typora写的.md文件拿到vscode能开扔到obsidian能开传到GitHub能自动渲染成网页发到掘金、知乎这类社区能直接粘贴发布。甚至同一个文件既能在手机上编辑又能交给脚本批量处理。这背后的原理很简单markdown是源文件不同的平台只是渲染器。源文件永远忠实保留你的内容渲染器负责把它变成漂亮的样式。这意味着你的笔记资产被彻底解放了——不会出现十年前用某国产笔记软件、后来软件停止维护、导出还要收费的惨剧。这个优势用markdown越久感受越深。1.3 半小时能学会、一辈子都在用投入产出比极高做个不严谨的估算花30分钟掌握核心语法标签之后每次写文档都能省下至少20%的排版时间。如果一年写100篇文档这半小时的投入能换来几十个小时的节省。而且更重要的是markdown的语法设计基本遵循所见即所猜——你看到一个#就知道是标题看到*就知道是强调不需要死记硬背。真正劝退新手的往往不是语法本身而是搜索到的资料质量参差不齐。有的手册列出了所有规范把不常用的交叉引用、脚注、定义列表全部摆上来看起来吓人有的教程又太简略换行都不讲。所以接下来这一节我直接把最有用的一整套语法标签整理成速查表顺便把表里每一行都拆开讲透。2. 一图速查markdown核心语法标签全表2.1 先看一张可以保存到本地的速查图这一节就是标题里说的一图秒懂。下面的图不是截图而是用markdown本身画出来的一份速查表你把它复制到任意markdown编辑器里就能秒懂。这也是markdown很妙的地方——它连自己都能作为内容被渲染成表格。# 一图秒懂markdown语法标签 | 功能 | 语法写法 | 渲染效果 | | ------------ | ------------------------------- | ------------------------------ | | 一级标题 | # 标题 | 标题最大 | | 二级标题 | ## 标题 | 标题次大 | | 三级标题 | ### 标题 | 标题中等 | | 加粗 | **加粗文字** | 加粗文字 | | 斜体 | * 斜体文字 * 或 _斜体文字_ | 斜体文字 | | 删除线 | ~~删除线~~ | 删除线 | | 行内代码 | code | code有底色 | | 代码块 | 语言名 ... | 带语言高亮的整块代码 | | 无序列表 | - 项目 或 * 项目 | 项目符号列表 | | 有序列表 | 1. 项目 2. 项目 | 数字序号列表 | | 任务列表 | - [ ] 未完成 - [x] 已完成 | checkbox | | 引用 | 引用文字 | 左侧竖线引用的块级内容 | | 链接 | [文字](https://地址) | 可点击的文字链接 | | 图片 |  | 图片 | | 分隔线 | --- | 横线分隔 | | 表格 | 用竖线、短横线、冒号组装 | 渲染成规整的表格 | | 换行 | 行尾加两个空格再回车 | 变成一个新的行而不是新段落 | | 数学公式 | $行内公式$ 或 $$块级公式$$ | 渲染为数学公式 | | 折叠块 | details summary标题/summary | 可展开折叠的容器部分编辑器支持 |提示把这份表存成md文件放进自己的笔记库里遇到语法想不起来的时候打开它比翻搜索引擎快得多——我就是这么干的比收藏几百篇教程实用。2.2 标题、段落与换行最容易栽跟头的地方标题语法没啥好说的#到######分别对应一级到六级标题。需要注意的有两点一是#后面必须有空格写成#标题在大多数渲染器里都不会生效只会显示成纯文本的#标题二是很多编辑器里同级标题会入自动大纲这让你不用装额外的目录插件就能实现文档内部导航。段落是markdown里默认的文本组织方式连续多行不带空格的文字会被合并成一个段落。真正的坑在换行如果你想在一个段落内部强行换行直接按回车是没用的渲染出来还是同一行。必须要在行尾加两个空格再回车才会真正换行。我知道这个设定很反直觉但它源于markdown最初的邮件文本设计——因为那个年代没有所见即所得两个空格就是硬回车的标记。如果你觉得每次敲两个空格太反人类有两条出路一是用typora这类编辑器它默认的回车即换行模式和Word一致二是在vscode里装一个markdown all in one插件配合设置项也能极大缓解换行问题。但你要明白规范就是规范把两个空格记成软换行符以后在任何编辑器里都不会迷惑。2.3 强调、删除线、分隔线和特殊符号的转义加粗、斜体和删除线这组文字修饰标签逻辑特别直白**两个星号**表加粗*一个星号*表斜体~~两个波浪线~~表删除线。而且它们可以嵌套组合比如***加粗斜体***就是又粗又斜这在写文章重点句时特别常用。分隔线是三个短横线---但这里有个很大的坑如果你在表格下面用了---它可能会被解读为表格的格式定义行而不是分隔线。另外有些编辑器里单独一个空行后紧跟---默认会帮你新建一个二级标题匹配了##标题语法的缩写。还有一点分隔线上下要留空行否则它紧贴段落会非常难看。特殊符号的转义要在前面加反斜杠\。比如你想原样输出#号就得写成\#否则渲染器会认为你是要建标题。同理*、_、、[]、{}这些有特殊语法含义的字符在不想让它触发格式的时候全都用反斜杠来转义。这个逻辑和大多数编程语言一样理解一次就能举一反三。2.4 列表无序、有序和任务清单的三重写法无序列表用-、*、都可以统一用一种就行。注意符号后面要跟一个空格再写字而且列表项之间最好保持同样的缩进层级——一个Tab或两个空格缩进就代表嵌套子列表。我见过很多新手把多层列表写得乱七八糟渲染出来层级混乱就是因为缩进不一致。有序列表更简单写1.、2.、3.就行。但有个专业技巧你可能不知道有序列表前面的数字不一定要按顺序渲染器会自动按序号显示。也就是说你全部写1.最终也会渲染成1、2、3、4……这样在增删列表项时就不用手动重新编号了这个特性在维护文档时能省不少事。任务清单task list是markdown对效率工具的绝妙补充语法是- [ ] 未完成和- [x] 已完成。中括号里是空格就是未勾选是x就是已勾选。在GitHub、vscode、obsidian里这些清单可以直接点击勾选。做个人任务管理、写作大纲都能用它比如我在写长文时就把大纲列成任务清单写一小节勾一小节非常有成就感。2.5 代码块与行内代码技术写作的命根子写技术文章的人最在意的就是对代码的支持。行内代码用单个反引号包裹适合在句子中夹一个函数名、命令或变量比如print()。代码块用三个反引号并在开头写上语言名比如python渲染器就会自动做语法高亮。关于代码块有几个细节值得记住第一代码块内部的文字不会被渲染你写**加粗**它也原样显示成**加粗**这是写教程最需要的安全特性第二语言名写错不会报错只是没有高亮常见的有js、python、java、bash、json、html、css第三如果你要在代码块里再嵌套一个代码块可以用四个反引号做外层包裹这个嵌套技巧90%的人不知道。2.6 链接、图片和引用让文章活起来的元素链接的语法是[显示文字](目标地址)目标地址可以是https开头的网络URL也可以是相对路径的本地文件比如[上一篇](./last-article.md)。这个相对路径特性在本地笔记库里非常方便——你在obsidian里用[[笔记名]]双链那是软件特性但跨软件通用的写法还是标准链接语法。图片的语法是和链接只差一个英文感叹号。替代文字在图片加载失败时会显示在正常渲染时鼠标悬停也会看到。图片地址同样支持网络URL和本地相对路径。后面我会专门讲图片路径这个高频大坑这里先记住基本语法。引用是用写在段落开头可以是单行引用也可以连续多行引用组成长篇。后面加一个空格、再接内容是常用的标准写法。引用可以嵌套就是引用里的引用。写文章时引用别人观点、摘录文档或者自己给自己加注释类似于博客的备注块全靠这个标签。3. 高频语法背后的隐藏细节与避坑指南3.1 图片路径的三种写法以及为什么你的图总是裂掉图片语法看着简单但实际操作时很多人立刻栽在路径上。写网络图片时地址必须是完整的URL包括https://协议头否则渲染器可能把它当作相对路径去本地寻找。写本地图片时有相对路径和绝对路径两种相对路径是相对于当前md文件所在目录的路径绝对路径是相对于整个电脑根目录的完整路径。我强烈建议你在写作时统一使用相对路径。比如笔记库目录结构是docs/笔记.md图片放在docs/images/图.png那么在笔记里的引用就该写成。这样做的好处是整个文件夹一起移动到别的电脑、推送到GitHub、上传到博客图片都不会丢。因为相对关系没有变。在typora里有个特别贴心的设置偏好设置里可以选择复制图片到指定目录并设置是否自动更新引用路径。这个习惯我从开始用markdown起就建立了任何需要插入的图片一律先拷到笔记同级的images目录下再用相对路径引用。这比你随便在电脑里放个绝对路径稳妥一万倍。另一个高频问题在vscode里markdown预览时图片能显示但推到GitHub就不显示了。大部分原因是路径包含了反斜杠\Windows习惯或者文件名有大写/空格。规范的写法是统一用正斜杠/文件名避免空格和中文或转成URL编码。这个细节说小很小但排查时极其费时间。3.2 表格语法常用列对齐以及为什么复制到Excel乱了markdown表格的写法是用竖线|分隔列第二行用短横线-区分表头和内容区。比如| 姓名 | 年龄 | 城市 | | ---- | ---- | ---- | | 张三 | 25 | 北京 | | 李四 | 30 | 上海 |渲染后就是一张规整表格。第二行里冒号的位置控制对齐方式默认是左对齐:---是左对齐---:是右对齐:---:是居中对齐。这个细节在表格数字列对比时特别有用右对齐会让数字的个位对齐看着舒服多了。表格语法本身不难但最让人头大的是复制粘贴。从markdown表格直接复制到Excel默认不会拆成行列全部挤进一个单元格。解决方案有几个一是用在线转换工具把markdown表格转成csv再导入Excel二是直接用pandocpandoc input.md -o output.xlsx能直接把文档转成Excel格式三是很多markdown编辑器支持复制为指定格式。我更推荐第二个方案因为pandoc是跨平台开源工具能处理复杂表格。3.3 数学公式LaTeX语法在markdown里的正确写法数学公式是另一大高频需求。markdown语法中有两套数学公式写法整行公式。行内公式用单个美元符号包围比如$Emc^2$渲染后公式嵌在文字里块级公式用双美元符号包围比如$$\int_0^1 x^2 dx$$渲染后公式独占一行且居中。公式的内部语法遵循LaTeX功能很大但基础需求只需要记住几个符号上标^下标_分号\frac{分子}{分母}希腊字母\alpha、\beta、\theta求和\sum积分\int根号\sqrt{}。这些符号组合起来能覆盖从中学到大学的绝大多数公式。需要注意并不是所有markdown编辑器都原生支持数学公式渲染。typora内设了MathJax引擎开箱即用vscode则需要安装markdownmath插件或使用带数学支持的预览扩展obsidian默认也支持。如果你在一个不支持的编辑器里写$公式$它只会被当成普通美元符号显示不会报错但也不会渲染。3.4 折叠块和分级细节高级但不复杂的加分项折叠块collapsible block不属于最基础的那20个语法标签但在需要收起长代码、默认展示结论的场景下极其好用。语法是HTML标签details summary点击展开查看详情/summary 这里写被折叠的内容支持markdown语法。 /details预览时只会看到可点击的点击展开查看详情点击后才显示内容。这在GitHub的issue回复里很常见在个人笔记里做答案先藏在折叠里自己回忆一遍再打开也很有趣。obsidian和typora对折叠块支持不错vscode需要配合预览插件。若你主要在某个编辑器里写作建议先测试兼容性再大规模使用。除了折叠块还有一个常被忽略的细节markdown标签前后的空行。我的经验是绝大多数语法元素标题、列表、代码块、引用、表格前后都留一个空行既能保证在各种渲染器里表现一致也让源码读起来更清爽。有人喜欢把所有内容挤在一起这在typora里也许没事换到GitHub上就会排版错乱。4. 编辑器与插件工作流选对工具体验翻倍4.1 新手先选一个所见即所得的编辑器markdown语法是通用的但编辑器的使用体验千差万别。我给新手的建议是第一优先级选typora。它是最早把markdown做成所见即所得的桌面级工具之一左边写右边实时渲染图片拖拽即可插入还自动帮你补全相对路径对几乎没有技术背景的人极其友好。另一类流派是源码分屏预览代表是vscode。它本体是代码编辑器但对markdown支持极强更重要的是插件生态无敌写md的同时还能顺手写代码、跑脚本、管理版本。我用vscode写技术博客已经好几年了不管是本地预览还是发布前的格式检查都相当顺手。obsidian则适合长周期的知识管理。它基于本地markdown文件支持双链、图谱、插件市场特别适合搭个人知识库。它的渲染风格偏简洁而且所有笔记都是md文件将来换工具零负担。如果你正处于想长期积累知识、又担心笔记软件绑架你的状态我建议直接上车obsidian。4.2 vscode里值得装的markdown插件清单vscode本身对markdown只能算能渲染真正的体验靠插件。我最常用的几款Markdown All in One自动生成目录、快速切换加粗斜体、自动格式化表格、快捷键补全新手装它就够了。Markdown Preview Enhanced增强预览功能支持数学公式、导出PDF/HTML、自定义CSS还能绘制高级图表预览快捷键是CtrlK V分屏预览和CtrlShiftV独立预览。markdownlint帮你检查语法不规范的地方——比如标题前后空行缺失、列表符号不一致、代码块语言未指定它都会用黄色波浪线提示对养成好习惯帮助极大。装完插件记得改两个地方第一个是文件关联把.md文件默认关联到markdown语言模式一般装完插件就会自动关联第二个是预览窗口的样式如果你觉得默认预览字号太小可以自己写一份CSS覆盖。这些配置都散落在settings.json里自己稍微调试一下就能让vscode的markdown体验不输给typora。4.3 markdown转PDF、Word、HTML的实用工作流写作完的markdown文件最终总要交付出去。最常见的导出需求是PDF和Word。最优雅的方案就是pandoc——堪称文档转换界的瑞士军刀。把md转Wordpandoc input.md -o output.docx把md转PDF需要LaTeX环境记得先装好pandoc input.md -o output.pdf --pdf-enginexelatex把md转HTMLpandoc input.md -o output.html -s --metadata title文章标题vscode里安装了Markdown Preview Enhanced之后也可以直接在预览窗口右键选择Export to PDF不需要装额外的LaTeX环境就能导出。另一个轻量选择是typora它的导出-PDF做得也很顺滑直接打开文件菜单导出即可。如果你有经常性md转Word并保持格式完整的需求还可以在coze或一些自动化平台里搭一个工作流上传md文件调用转换节点直接输出Word。这类需求本质就是把pandoc封装成服务适合团队内部共享。个人用的话本地装pandoc一劳永逸。4.4 网页内容怎么一键变成规范markdown平时在网上看到好文章总想保存成markdown放进自己的笔记库。最实用的方案是浏览器插件markdownload安装后在网页上右键就能把当前页面正文提取为markdown还支持自定义提取规则、保持图片链接。虽然说提取质量不能保证100%完美但对大部分博客和文档网站效果已经相当不错。另一个思路是用在线转换工具直接把网页内容粘贴进去它自动抽取正文并转成markdown。这类工具多如牛毛我建议你在收藏夹里存两个备用就行。需要特别提醒的是不管用什么方式从网页转markdown转换完成后一定要人眼检查一遍图片链接、标题层级和代码块是否完整我曾经遇到过转换结果里把代码块的三个反引号吞掉的情况导致整篇文章格式崩掉。如果你追求更自动化还可以用jupyter notebook场景里常见的方案把网页先保存成html再用pandoc做html - md的转换一些已经不支持在线更新的老旧网页内容这个方法往往比在线插件更可靠。5. 编辑器之间的兼容性与选型深入对比5.1 同样是markdown语法为什么在不同软件里渲染不一样很多人困惑同一份md文件在typora和github上打开效果怎么不一样原因很简单——markdown规范在基础语法之外不同平台会扩展自己的方言。GitHub上有GitHub Flavored MarkdownGFMGitHub风格扩展typora和obsidian也各有自己的高亮语法、双链语法等特性。最经典的分歧就是任务列表基础markdown规范没有定义- [ ]GitHub支持typora支持vscode支持但某些轻量渲染器会原样显示成- [ ]。所以如果你要写一份能到处跑的markdown尽量只用GFM覆盖范围内的语法——标题、列表、表格、代码、引用、链接、图片这些最安全。5.2 图片与附件的管理方案对比图片管理其实是markdown笔记体系里最关键的一环。typora的做法是本地相对路径物理复制obsidian则默认把附件统一放入指定附件文件夹vscode基本上全靠你自己维护目录结构——因为它就是个编辑器不管你的资源。我的建议是不管用哪款一律把附件放在笔记同级的assets或images目录并用相对路径引用。如果担心笔记多而杂可以按一个大主题建立一个文件夹里面同时放笔记和素材这样既好备份也好同步。图床则是更进阶的方案把图片上传到对象存储远端得到一张图片URLmd文件里直接引URL。适合写博客、发社区的人因为没有本地资源依赖任何平台一贴就能显示。但本地笔记因为离线优先考虑用相对路径更稳。我的习惯是本地笔记全部相对路径发布到博客时再统一处理成图床链接。5.3 目录、锚点与内部跳转长文档写作时目录TOC几乎是刚需。在vscode的Markdown All in One里打开命令面板CtrlShiftP输入Markdown All in One: Create Table of Contents即可生成目录并可以跟随标题变化动态更新。typora则是在标题右键直接插入目录GitHub也会自动为所有标题生成锚点并显示在页面顶端。内部跳转依赖于标题的锚点规则在GFM中标题## Hello World对应的锚点约定是#hello-world——全部转小写、空格转短横线、移除标点。所以你在文章里可以用[跳转标题](#hello-world)做站内锚点。这个技巧在一个很长的技术文档、FAQ页面里特别实用。5.4 从jupyter notebook到obsidian不同场景的语法选择jupyter notebook用户经常需要在笔记单元里写说明文字在其中使用markdown语法是一样的但有个值得注意的点jupyter里的markdown渲染默认不支持所有语法比如与某些复杂表格和HTML标签的兼容性较差。在notebook里我更推荐用GFM基础子集特别是标题、列表、代码块、公式这些是最稳的组合。obsidian用户则要熟悉它的双链语法[[笔记名]]和#标签这些在obsidian中极其强大因为它们是知识网络连接器但是从obsidian导出的md文件标准的markdown渲染器会原样显示双链文本不会变成可点击链接。如果你想把obsidian笔记发布到博客需要先用插件把双链转换成普通的markdown链接。5.5 用markdown四象限图来理解自己的学习路径把上述内容放到更宏观的视角来看可以用一个四象限帮读者定位当前阶段。第一象限是纯阅读者只用markdown做简单备注事实上连语法都不必背选个typora就能边看边学第二象限是日常写作者需要掌握前面那20个标签用typora或obsidian做笔记、写周报第三象限是技术发布者需要在vscode里配插件、用pandoc导出、处理图片路径这是技术博主和文档维护者的日常第四象限是高级自动化用户要求不仅能写还能用脚本批量处理md文件、用API调起转换工具把markdown嵌入到自己的自动化工作流中。你不需要一开始就追求第四象限。大多数新手的快速通关法则是先用typora写一周把语法在真实写作中过两遍再决定是否迁到vscode或obsidian。语法是通用的熟练度才是真正要积累的东西。6. 常见问题排查与实操心得6.1 换行不生效、预览和想象不一样排查思路很简单先把渲染效果打开对照源码和预览看。如果文字确认为同一段而你想换行却没换十有八九是行尾没加两个空格。如果加了两个空格还是不换行可能是编辑器的严格模式关掉了在设置里搜索trim_trailing_whitespace把相关的保存时去除行尾空格选项关掉就行——这个坑在vscode里非常经典。6.2 表格渲染变形或直接显示为横线表格变形通常是因为表头分隔那行的短横线数量太少或不一致。其实短横线数量不影响渲染但确保至少有两个短横线。更常见的问题是表格前后没有空行导致上一段正文和表格混在了一起。在markdown里表格和列表一样是需要空行保护的元素前后各留一个空行基本能杜绝绝大多数格式错乱。如果你写了表格但预览里只显示一行横线那大概率是分隔线的写法被解析成了---而不是表格的第二行。打个最简单的排查方法把表格的每一列之间都用|对齐第二行用| ---- | ---- |不要省略两端的竖线。虽然有些渲染器允许省略边缘竖线但加上是最保险的。6.3 代码块语言没高亮、公式显示不出来代码块语言没高亮先检查语言名是否写在三个反引号同一行且拼写正确。python可以py不一定所有渲染器都认尽量用官方语言标识。公式渲染不出来大概率是编辑器的数学支持被关掉了——在typora的偏好设置、vscode的Markdown Preview Enhanced设置里都有一个math开关找到它并打开。6.4 图片显示不出来、路径怎么改都对不上我的排查顺序是先看图片文件是不是真的存在那个路径再检查文件名大小写是否完全一致很多服务器文件系统是区分大小写的再看是否使用了绝对路径临时能用但一搬文件夹就裂。如果是网络图片记得检查链接是否完整、域名是否可达。如果本地路径里出现中文或空格先测试改成英文文件名——我见过太多人卡在这种地方。6.5 从网上复制的代码或表格粘贴进来就乱从网页复制的表格粘贴进markdown编辑器经常变成一行纯文本或一堆竖线。标准解法是先在富文本场景比如Word里粘贴成表格再用在线转换工具转成markdown表格。代码块乱的解决方式更简单粘贴前先缩进一个Tab或者粘贴时选择粘贴为纯文本。还有一个经验值得分享我们的内容是针对新手进行的基础指导但不承诺工具和一切外部链接永久可用。在互联网上工具是流动的学会了语法你永远不会失去核心能力。7. 最后再分享一点我的markdown使用体会写markdown久了最大的感受是它把我从排版焦虑里解放了出来。以前用Word我最讨厌的就是贴代码和调整列表缩进光标点来点去格式还是乱的。换到markdown后手只需要在键盘上流动想加粗就包两个星号想插入代码就写三反引号思路完全不用被打断。坚持几个月后我甚至反过来把写PPT的思维也换成了markdown——先用标题做骨架再用列表提炼要点最后才套模板效率比过去高很多。如果你刚开始接触markdown我给你的建议是从typora或obsidian选一个先把这篇里讲的20个语法标签过一遍然后去写几篇真实的笔记或文章。不要试图一次背完所有语法也不用急着折腾各种插件和pandoc写作本身才是最重要的。遇到语法想不起来回来翻这篇文章里的速查表就够了。等你彻底习惯了markdown这种以纯文本为源、到处可渲染的思维方式你大概率会和我一样再也回不到那个被格式工具栏绑架的写作状态了。