Markdown 写作指南：从编辑器选型到高频语法与生态联动

很多人第一次搜Markdown 安装使用教程以为是下载某个叫 Markdown 的软件。其实 Markdown 是一种轻量级标记语法不是什么独立程序。真正需要你装的是编辑器——一个好用的编辑器能让 Markdown 从记事本里写符号变成高效、可维护、可协作的文档工作流。这篇教程我从自己踩过的坑写起覆盖编辑器选型、VS Code 从安装到插件配置、高频语法细节换行、表格、图片路径、以及表格转 Excel、Mermaid 预览、Obsidian 折叠、WordPress 引用、Jupyter 目录这些社区里天天有人问的场景。无论你刚开始接触还是已经写了一阵子但总被某个小问题卡住都能在这里找到能直接照抄的答案。1. 编辑器选型从踩坑到稳定组合1.1 先搞清楚Markdown 不是软件但编辑器必须选对我见过不少朋友问Markdown 怎么下载这个问题本质上是把语法和工具搞混了。Markdown 从诞生起就是纯文本格式你用 Windows 自带的记事本都能写写好存成.md后缀就行。真正拉开体验差距的是你在什么编辑器里写、怎么预览、怎么管理图片和文件。刚接触时我也走过弯路。先是用记事本硬写体验到语法之后又换过好几个编辑器还因为某个软件收费的问题来回折腾。最后发现一个规律没有最好的编辑器只有跟你的场景最匹配的编辑器。写博客 README 和写日常笔记不是一回事批量处理文档和维护个人知识库也不是一回事把工具固定在一款上反而会让工作流变得别扭。1.2 三款主流 Markdown 编辑器的横向对比目前被提起最多的三款是 Typora、Obsidian 和 VS Code。我三款都用过至少半年以上各自特点很明显。维度TyporaObsidianVS Code收费付费授权免费可付费同步免费开源平台Windows / macOS / LinuxWindows / macOS / Linux全平台预览方式所见即所得编辑预览分离可切换分离式预览插件生态弱主打轻量极强社区插件多极强全场景覆盖适用场景零门槛快速记录个人知识库、双链笔记写文档、写代码、批量处理Typora 最舒服的地方是所见即所得写标题直接变标题没任何学习成本适合不想折腾的人。Obsidian 最大的卖点是本地文件管理和双链笔记多了以后知识网络的价值才体现出来。VS Code 则是全能选手它本质是代码编辑器但装几个插件后 Markdown 能力不输任何专用编辑器而且跟 Git、命令行、脚本配合起来写技术文档的效率非常高。1.3 我最终保留下来的组合方案折腾一圈之后我现在的方案是VS Code 主力写文档和博客源文件Obsidian 管个人知识库Typora 偶尔用来快速临时记录。听起来是三个工具其实定位不重叠。写线上博客、项目 README、接口文档时我需要严格的语法控制、markdownlint 检查、一键预览和 Git 版本管理VS Code 最合适。日常学习笔记需要互相引用、长期沉淀Obsidian 的文件夹结构和双链是无可替代的。Typora 则像一支便利贴开机即写不占脑子。这种组合的好处是每个工具都只做自己最擅长的事不会因为单一工具的功能边界而去妥协。我也建议不要一上来就装一堆插件先把主流程跑通再按需加东西。2. VS Code 下搭建 Markdown 写作环境安装、插件与快捷键2.1 VS Code 本体的下载与安装要点VS Code 从官网直接下载就行安装文件是.exeWindows。有两点值得提醒。第一安装时尽量勾选添加到 PATH。这样做的好处是以后可以在任意终端里输入code .直接打开当前目录。很多写文档的人是从命令行工作流切入的这个功能省事很大。第二文件关联默认勾选即可让.md文件默认用 VS Code 打开后面省去右键选择的麻烦。装完以后建议顺手设置一下中文界面。打开 VS Code按CtrlShiftP输入Configure Display Language安装 Chinese (Simplified) 语言包重启后用起来会更顺手。这一步属于装不装都行的体验优化不影响核心功能。2.2 必装插件清单每个插件解决什么问题VS Code 装完只是骨架Markdown 体验全靠插件。这里列一份我实际长期在用的清单插件解决什么问题是否必装Markdown All in One自动目录、列表缩进、表格格式化、快捷键补全必装Markdown Preview Enhanced增强预览支持导出 PDF、TOC、自定义 CSS推荐markdownlint语法规范检查黄色波浪线提醒强烈推荐Markdown Preview Mermaid Support让原生预览支持 Mermaid 图表需要画图时装Paste Image剪贴板截图直接粘贴为图片文件必装Markdown All in One 是我装完 VS Code 后第一个会装的插件。它对新手最友好的一点是写列表时回车会自动保持缩进不需要手动打-或数字写完标题后运行Create Table of Contents目录直接生成在光标位置维护长文档时非常香。markdownlint 不一定适合所有人。如果你在团队里维护规范文档它能让所有人的写作风格统一减少不必要的格式 diff。如果只是私人记录装了可能会觉得波浪线吵可以装完再按需要关掉部分规则这个我在第 4 章会细说。2.3 三分钟内配好快捷键和文档模板VS Code 里两个快捷键是 Markdown 写作必须记住的CtrlShiftV在当前页签打开预览CtrlK V在右侧打开实时预览我日常用这个最多如果装了 Markdown All in One还有两个高频快捷键CtrlB加粗CtrlShift]快速切换标题级别。写成习惯之后基本不会碰鼠标点工具栏。再分享一个写博客源文件很实用的小技巧做一份带 Front Matter 的文档模板。打开 VS Code命令面板搜Configure User Snippets选 Markdown然后粘贴如下内容{ Post Front Matter: { prefix: fm, body: [ ---, title: \$1\, date: \$CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE\, tags: [\$2\], ---, , $3 ], description: Insert front matter blog header } }之后新建.md文件输入fm再按 Tab模板自动填好。这套东西折腾一次能用几年写技术博客、项目说明都能直接套。3. 高频语法扫盲换行、表格、图片路径、任务列表与特殊符号3.1 换行问题为什么我回车了还是不换行这是搜索热度最高的问题之一。很多人刚从 Word 迁移过来写完一行按回车发现预览里两行挤在一起以为软件坏了。原因在于 Markdown 的换行规则和普通文本编辑器不同。单纯按一次回车在 Markdown 里只是软换行渲染时会被当成空格真正要产生换行有三种做法在行尾加两个空格再回车在段落之间留一个空行渲染成独立段落直接写 HTML 的br标签。实际使用中我最推荐第二种。两个空格的方式太隐蔽保存后再看常常漏掉HTML 标签写着多一层噪音空行最直观任何编辑器里都能一眼看出来而且渲染出的段落间距也更清晰。3.2 表格语法对齐方式与竖线转义Markdown 表格是 GFMGitHub Flavored Markdown的扩展语法标准 CommonMark 本身并不支持。所以如果你在某个编辑器里写的表格没生效先确认编辑器的方言是否支持 GFM。一个最基础的表格是这样写的| 名称 | 价格 | 备注 | | ---- | ---- | ---- | | 苹果 | 5.00 | 水果 | | 西瓜 | 12.00 | 夏季限定 |对齐方式通过第二行的冒号控制冒号在左边左对齐右边右对齐两边都有居中对齐| 左对齐 | 居中 | 右对齐 | | :----- | :--: | -----: | | 1 | 2 | 3 |表格里有个容易踩的坑如果单元格内容本身需要竖线比如格式 A|B必须写成\|转义否则表格会多出一列。另一个常见问题是表格列太多时手敲对齐线很累我一般直接让 Markdown All in One 的Format Table功能重排选中表格区域执行命令即可。3.3 图片路径的四种写法与失效排查图片是 Markdown 里翻车率最高的部分因为写入方式和实际渲染环境经常对不上。常见写法有四种!-- 1. 相对路径 --  !-- 2. 绝对路径 --  !-- 3. HTML 标签可控制大小 -- img src./images/01.png width50% alt截图 !-- 4. 图床 URL -- 相对路径适合本地写作、随项目一起提交到 Git 的场景移动整个文件夹不受影响推荐作为默认方案。绝对路径写起来简单但换台电脑路径就挂。使用 HTML 标签主要解决图片尺寸问题——Markdown 原生语法没法设置宽度想让图片显示为 50% 就需要用到img。图床 URL 适合文中插图有外部链接的情况但图床稳定性要自己控制。如果图片在预览里裂了排查路径按顺序来确认图片文件真实存在且后缀名大小写一致确认路径里没有中文、空格等特殊字符有就改名确认相对路径的位置是相对于.md文件所在目录而不是编辑器打开的根目录确认文件名里的括号、空格有没有被转义。VS Code 里用 Paste Image 插件能省掉大部分路径烦恼。按下CtrlAltVWindows剪贴板里的截图会自动存到当前目录并在文档里插入相对路径格式的引用。关键是先在设置里把pasteImage.path配好我一般配成${currentFileDir}/images图片自动归入 images 子目录不会把仓库根目录弄乱。3.4 任务列表和带圈数字的输入任务列表在 Markdown 里很常用写法是在列表项前加[ ]未完成或[x]已完成- [ ] 写第一章 - [ ] 画架构图 - [x] 完成 review这里有个细节任务列表依赖 GFM渲染出来是带复选框的样式。在 Obsidian、Github、VS Code 预览里都没问题但部分普通 Markdown 渲染器可能显示成普通列表要注意环境兼容。带圈数字①②③这类字符跟 Markdown 语法没有关系纯粹是字符输入问题。最快的方法是在中文输入法里直接输入拼音yiersan候选词里一般都有带圈数字。如果你一定要用标准写法也可以用 HTML 实体#9312;表示①#9313;表示②以此类推这样在支持行内 HTML 的渲染器里也能显示。4. 实操场景实录表格转 Excel、Mermaid 预览、lint 波浪线4.1 表格复制到 Excel 后错乱三种解决路径在浏览器预览里选中表格直接 CtrlC 复制到 Excel大概率得到一个竖线残留、列错位的乱摊子。原因是 Markdown 表格在渲染后虽然显示得很整齐但复制时 Excel 拿到的是带分隔符和格式的混合文本自动分列的逻辑和你的预期不一致。我的解决路径有三条按使用频率排序方案一先纯文本清洗再分列。把复制内容先粘贴到记事本确认里面还带着|符号后再全选复制然后到 Excel 里粘贴。接下来用 Excel 的数据 → 分列 → 分隔符号勾选其他并填入|就能整齐分好列。这个办法不依赖任何第三方工具也是我平时最常用的。方案二在线表格转换工具。站内搜索markdown table to excel能直接找到现成的转换器把 Markdown 表格代码粘贴进去导出成.xlsx文件。适合一次性转换比较大块的表格。方案三写脚本自动化。如果隔三差五就要处理几十个表格再手动分列就太亏了。我一般用 Python 的 pandas 或 csv 模块把每行按|切分后写入 Excel逻辑很简单但一旦跑通就能批量处理。4.2 Mermaid 预览支持与预览快捷键很多人搜索markdown preview mermaid support 预览 快捷键是因为 VS Code 原生的 Markdown 预览默认不支持 Mermaid 图表。就算你在.md文件里写了 Mermaid 图表代码预览面板也只会显示一个代码块这会让第一次用的人误以为语法写错了。解决办法是安装 Markdown Preview Mermaid Support 插件。装完后VS Code 内置的CtrlShiftV预览面板就会自动识别并渲染 Mermaid 图表代码。注意区分这个插件是增强原生预览的如果你用的是 Markdown Preview Enhanced它本身已经内置 Mermaid 支持不需要同时装两个避免功能重叠。打开预览的快捷键我再说一遍CtrlShiftV直接预览当前文件CtrlK V在侧边打开预览后者边写边看效果更方便。真正需要出图时Obsidian 对 Mermaid 的支持也很完整双链笔记里画流程图可以直接写不需要额外配置。4.3 markdownlint 飘满黄色波浪线时怎么办装完 markdownlint打开稍微旧一点的文档满屏黄色波浪线是常态。这不是文档写错了而是 lint 规则在按白皮书标准审查你。最常见的几条规则规则含义什么时候可以关MD013单行长度限制为 80 字符写中文文档经常误报建议调大MD024禁止重复标题内容多章节模板文档容易误报MD033禁止行内 HTML需要写img控制图片大小时关掉关闭方式是在项目根目录建一个.markdownlint.json{ MD013: { line_length: 120 }, MD033: false }保存后波浪线会按新规则重新计算。我的建议是个人笔记里保留 lint 但放宽条件团队规范文档里则严格按规则来减少协作时因为格式不一致产生的脑力损耗。5. 生态联动玩法Obsidian 折叠块、WordPress 引用、Jupyter 目录5.1 Obsidian 里 Markdown 块怎么折叠Obsidian 的 Markdown 格式块可以折叠吗这个问题每次有人问都能引来一堆答案。实际体验分两种情况。第一种列表折叠。Obsidian 支持通过列表缩进实现折叠在编辑模式下写出多级列表然后用 Tab 缩进子项预览或阅读模式下点击列表左侧的小箭头就能折叠和展开这个列表块。这个能力是 Obsidian 原生支持的不需要额外插件。第二种自定义折叠块。用 HTML 的details和summary标签details summary点击展开查看内容/summary 这里是被折叠的内容支持 Markdown 语法。 /details在 Obsidian 阅读模式下这个折叠块会渲染成可点击展开的区域。来源笔记里放代码方案、FAQ 很合适。需要注意折叠块里的 Markdown 内容能不能正常解析取决于渲染器对 HTML 块内 Markdown 的处理不同软件表现略有差异我试下来 Obsidian 和多数静态站点生成器都支持得不错。5.2 WordPress 上引用 Markdown 的三种做法WordPress 默认的块编辑器Gutenberg本身不解析 Markdown所以想在站点里用 Markdown 发内容有三种常见路径。做法一Jetpack 内置 Markdown 模块。Jetpack 插件设置里有个写作 → 使用 Markdown 撰写文章的开关打开后文章编辑框里可以直接使用 Markdown 语法。要注意的是启用后同一篇文章不要在 Markdown 和富文本之间来回切换否则编辑器会插入多余的 HTML 标签重新渲染时容易出双换行的问题。做法二装第三方 Markdown 区块。如果你用的是块编辑器可以在区块市场里搜 Markdown找到专门把区块内容按 Markdown 渲染的插件。这种方式更精细不会影响全局设置适合只在特定文章里使用。做法三主题开发用 Parsedown 解析。如果需要在自己的主题里动态解析 Markdown比较成熟的做法是用 Parsedown 这个 PHP 库。写一个简单的短代码封装一下前端就能直接把 Markdown 内容渲染成 HTML。这种方式灵活度高适合有定制需求的开发者。5.3 Jupyter Notebook 自动生成 Markdown 目录Jupyter 里的 Markdown 单元格是支持标准语法的写好#标题后目录生成有现成方案。如果你还在用 Jupyter Notebook经典版建议安装jupyter_contrib_nbextensions然后启用 Table of Contents (2) 插件。操作步骤pip install jupyter_contrib_nbextensions jupyter contrib nbextension install --user重新启动 NotebookNbextensions 标签页里勾选 Table of Contents (2)左侧会生成一个自动折叠的目录面板根据所有 Markdown 标题层级自动组织。如果用的是 JupyterLab新版已经内置左侧目录视图不需要额外安装。另外如果习惯在 VS Code 里编辑.ipynb文件Markdown 标题同样能通过 VS Code 内置大纲面板展示层级按CtrlShiftO直接跳转。最后再分享一个小技巧写 Markdown 这几年我最大的体会是别太依赖所见即所得。宁可花两小时把 VS Code 插件、路径规则、lint 配置一次调好也不要每天手动处理图片路径和表格格式。真正把 Markdown 当作纯文本 规范的组合来用之后你会发现它不仅能写博客、写 README还能写接口文档、写周报、写知识库。哪个编辑器顺手就用哪个关键是形成自己的固定流程让工具去适应你而不是反过来。