我第一次认真对待Markdown是因为在GitHub上一份README。当时觉得奇怪明明就是纯文本怎么渲染出来像一篇排版工整的文档后来我才知道这类文件背后用的就是Markdown标记语言而我一直在琢磨的那个“编辑器”其实只是它的一层外壳。很多Markdown编辑器首次打开时都会给你一份默认示例文档标题就叫“欢迎使用Markdown编辑器”这句话对新手来说真的挺友好它没有让你去背语法而是让你先敲几个符号再切到预览看看发生了什么。这篇东西我不想写成干巴巴的语法手册而是想从一个实际使用者的角度把Markdown编辑器的选型、语法细节、常见坑位、工作流衔接一次讲清楚。你可能是刚下载了一个Markdown编辑器、正准备抄起键盘学语法的纯新手也可能是被图片路径失效、换行不生效折磨过一轮的进阶用户看完这篇应该都不会亏。1. 先搞清楚Markdown到底是什么和普通编辑器差在哪1.1 Markdown不是“编辑器”而是一套标记语言这里先纠正一个高频误区很多人搜“Markdown编辑器”时默认Markdown是个软件其实它是一种轻量级标记语言和HTML、LaTeX算远房亲戚只不过设计目标特别纯粹让写作者用纯文本表达结构而且表达方式接近自然语言。你打开记事本也叫编辑器打开VS Code也叫编辑器打开Word也能管它叫编辑器。但“Markdown编辑器”指的是“能理解Markdown语法并把它渲染成好看格式”的那类工具。这里面牵扯到另一个经常被搜索的词编译器和编辑器的区别。传统意义上的编译器是把高级语言翻译成机器码的程序比如GCC编译C代码而Markdown的转换过程更像“排版引擎”它把# 标题这种轻量标记翻译成HTML、PDF、Word等格式中间不需要生成可执行文件所以我们一般不叫它编译叫渲染叫解析。理解这一点非常关键。它会直接影响你使用Markdown的方式你不是在排版而是在写结构化的纯文本排版的事交给渲染引擎。你用**加粗**标出一段重点预览时看见加粗了那是渲染器做了它该做的事导出成PDF发现字体不太对那不是Markdown的问题是你选用的导出工具渲染能力有限。1.2 为什么用Markdown写作它解决了哪些痛点这个问题如果不去实际用光听人安利是感受不到的。拿Word对比一下写一份五页文档你可能要反复调整标题字体、行距、列表缩进、图片居中一份文档改十遍版式都不稀奇。但用Markdown写作你从头到尾只关心一件事内容有没有表达清楚。标题大小用几个#控制列表层级用缩进和符号控制加粗斜体就包两个星号这些规则一旦形成肌肉记忆写起来真的像飞一样。Markdown还有一个被低估的巨大优势纯文本格式对版本管理极度友好。你写一份技术方案想用Git做版本追踪Word文档二进制格式会让diff变成天书而Markdown文件本身是文本每一行的改动都清清楚楚。做知识管理的人更懂这个痛点Obsidian、Logseq这类工具把整库笔记做成md文件配合坚果云或Git同步数据永远不会被某个私有格式锁死。跨平台迁移就更不用说了Windows、macOS、Linux、手机端随便哪个平台都能读能写。1.3 你其实不一定要单独安装一个“Markdown编辑器”这里有个反直觉的建议如果只是想体验一下完全不用急着下载软件。GitHub上编辑README后台自带Markdown编辑器语雀、知乎、掘金这些平台写文章时也直接支持Markdown语法Jupyter Notebook里写分析报告单元格切到Markdown就能用。你完全可以在这些现成的框里先写出感觉确定离不开了再考虑安装专门的Markdown编辑器。但如果你准备长期用来写博客、记笔记、维护项目文档那确实值得花点时间挑一个趁手的工具。下面我从本地写作、程序员场景、在线轻量三个维度结合“Markdown编辑器推荐”时高频出现的几款工具说说我自己的选型思路。2. 工具选型从“欢迎使用Markdown编辑器”开始的实践路线2.1 想要快速体验先打开自带的示例文档不管你是装了Typora、Obsidian还是VS Code插件第一次新建文件多半会看到“欢迎使用Markdown编辑器”这份默认文档。别再把它当废纸一样删掉了这其实是一份精心设计的入门素材里面通常已经写好了标题、加粗、斜体、列表、链接、图片、代码块的示例。我的建议是打开示例文档之后什么都别配置先把每个示例改动一下比如把标题文字改成自己的名字把链接换成自己常逛的网站把图片路径换成本地一张真实照片。改一个看一次预览效果强迫自己理解“源码”和“渲染结果”之间的对应关系。这个过程用不了二十分钟但比背十页语法手册管用得多。2.2 本地写作派Typora、Obsidian、Joplin怎么选如果你明确知道自己要拿Markdown做什么选型其实就清晰了。工具核心定位优点可能要注意的点Typora纯粹的Markdown写作工具沉浸式写作“所见即所得”的体验最自然导出PDF、Word、HTML都很方便早期版本免费后续版本需要付费授权Obsidian本地知识库双链、图谱、插件生态特别丰富所有笔记都是本地md文件隐私性很好上手有点门槛插件太多容易陷入折腾插件而不是写笔记的状态Joplin开源笔记应用免费开源支持端到端加密同步笔记和待办事务整合得不错编辑器本身比Typora朴素一点如果你是博客作者、要写技术文档我建议优先试Typora它的编辑器体验是三家里面最“干净”的。如果你打算搭一个长期使用的个人知识库Obsidian更合适因为它的网状笔记能力不是普通Markdown编辑器能比的。如果你对开源和隐私同步有硬性要求Joplin是稳妥的小众选择。2.3 程序员与极客VS Code Markdown插件程序员大部分时间其实就在代码编辑器里泡着如果只是写写README、整理技术笔记完全可以不切换到独立软件直接用VS Code就能把Markdown玩得很转。VS Code原生已经内置了Markdown预览能力只不过很多人不知道快捷键而已CtrlK V是侧边打开预览CtrlShiftV是整屏预览。要让写作体验再上一个台阶我推荐几个VS Code插件Markdown All in One自动生成目录、格式化表格、快速插入链接图片功能很全。Markdown Preview Mermaid Support给预览加上流程图支持装完之后写图表也能实时预览。Paste Image截图后直接粘贴插件自动把图片保存到指定目录并把相对路径写进md文件。markdownlint像代码检查工具一样提示格式问题帮你培养规范的Markdown写作习惯。顺带一提除了VS CodeVim、Zed、甚至手机上的Acode这类编辑器也有对应的Markdown支持方案。但新手真的没必要追求这些大部分需求用VS Code就够顶很久了。2.4 纯在线与轻量方案什么时候不需要装软件我也有一类场景是懒得开本地软件的只想临时把一段文本整理成Markdown格式或者从网页上摘录点内容。这时候在线编辑器就方便了代表性的有Dillinger、StackEdit这类打开网页就能写写完导出或复制走。网页内容剪藏也可以考虑MarkDownload这类浏览器扩展能把网页正文直接存成md文件非常利于收集写作素材。但用在线工具要注意两件事第一重要内容及时下载到本地不要只存在某个第三方页面里网站打不开或维护的时候你就傻眼了第二包含敏感信息的文本不要放上去在线编辑的数据始终在别人服务器上这个边界要清醒。搜索“Markdown编辑器下载”时我也建议大家认准官网或官方应用商店优先选有明确维护团队的工具。这个圈子因为开源生态繁杂出现过不少打着“Markdown编辑器”名义捆绑安装包的坑货装完编辑器电脑上多出一堆全家桶真的得不偿失。3. 核心语法与高频操作照着抄就能上手3.1 常用语法速记表下面这份表我建议你截图保存或复制进自己的笔记。能用Markdown写文档的人不是因为他记住了所有语法而是他面前有一张够用的速查表。用法写法示例渲染效果说明标题# 一级标题、## 二级标题最多支持六级标题井号后面记得有空格加粗**加粗**两个星号包裹斜体*斜体*一个星号包裹删除线~~已删除~~两个波浪线包裹引用 引用内容前面加大于号无序列表- 列表项减号、加号、星号都可以有序列表1. 第一项数字加英文句点加空格行内代码代码反引号包裹代码块python三个反引号可标注语言实现高亮分割线---三个或以上的减号链接[文字](网址)方括号包文字括号包地址图片在链接语法前多加一个英文感叹号3.2 换行与段落为什么按了回车还是没换行这是被问得最多的问题没有之一。Markdown里的换行规则和Word非常不一样普通按一次回车在很多Markdown引擎里只会当作一个空格并不会另起一行。真正起新段落需要在两段文字之间空一行。比如下面这种写法在渲染后两个字可能会挤在一起第一行 第二行常规的解决办法有三个第一种是段落之间加空行这是最标准、最推荐的第二种是行尾敲两个空格再回车相当于“软换行”渲染结果里会换行但不会产生段落间距第三种是直接写一个br标签这是HTML的行内换行标签在Markdown里是合法的。现在的编辑器大多也支持ShiftEnter直接软换行Typora、Obsidian都这样处理用起来非常顺手。顺便说一句有人以为表格里换行很麻烦其实表格单元格里插入br标签是最常见的做法比用空格硬撑省心得多。3.3 图片路径为什么图片总是显示不出来图片问题在热搜词里占了很大篇幅我索性把该说的都说透。Markdown里图片语法很简单方括号里的内容是“替代文字”图片加载失败时显示的就是这段文字括号里的路径才是真正的关键分为三种情况网络图片直接填URL比如。前提是这张图能正常访问。我建议你先在浏览器里打开一遍这个URL如果浏览器都打不开编辑器里自然也可能加载不了。本地绝对路径比如C:/Users/me/Pictures/a.png或/Users/me/Pictures/a.png。这种写法只在你现在的电脑上有效文件一旦换目录、换电脑路径就失效了。本地相对路径比如assets/a.png意思是“当前md文件所在目录下assets文件夹里找a.png”。这是我最推荐的写法。实际操作里每个写作项目我都建议搭配一个assets目录结构如下我的文档/ ├── 笔记.md └── assets/ ├── 截图1.png └── 截图2.jpg然后在笔记.md里这样引用这样整个文件夹拷给别人、推上Git仓库图片都不会丢。Typora可以在偏好设置里设置“插入图片时复制到指定路径”勾选后你直接拖图片进来它会自动帮你存到assets目录并生成相对路径。VS Code装了Paste Image插件后粘贴截图的体验类似。我在实际使用中还踩过一个经典的坑图片文件名包含空格和中文。一部分渲染引擎会自动转义一部分不会结果就是别人电脑上显示正常、你这边裂图。最稳的办法是文件命名从一开始就别带空格和中文用2025-06-demo-01.png这种风格一劳永逸。3.4 超链接标签和图片标签看起来像但完全不一样有人老把超链接标签和图片标签搞混我理解因为它们的语法结构确实只有一字之差。超链接写法是[文字](地址)图片写法是区别就是图片语法多了一个英文感叹号。这个感叹号千万别漏漏了渲染出来的效果就完全错了原本想放图的地方会变成一个可点击的文字链接点击后浏览器还打不开图片地址。我见过有人排查半天最后发现就是差一个!这种低级错误真的很搞心态。图片还能套进链接里生成一个“点图片跳转”的效果语法是把图片当作链接文字[](跳转链接)这种写法在博客里很常见比如点击封面图进入正文页背后就是这一段嵌套语法。3.5 表格、数学公式与目录文档档次唰地一下上去了基础语法练熟之后想让文档显得专业接下来值得学的是三件套表格、数学公式、目录。表格语法的骨架是竖线加短横线。第一行是表头第二行是分隔行分隔行里的冒号控制对齐方式---代表左对齐:--:代表居中对齐--:代表右对齐。示例| 姓名 | 年龄 | 城市 | |:---|:---:|---:| | 张三 | 25 | 上海 | | 李四 | 30 | 北京 |有人问表格怎么快速转换成Excel最暴力的方法是把Markdown表格粘贴进Typora预览再从预览里复制粘贴到Excel表格结构基本能保留。如果手头只有纯文本可以用在线“Markdown表格转换Excel”工具或者用Python的pandas去读HTML表格但不建议为了转一次表格写一堆代码性价比不高。数学公式的体验则跟编辑器绑得很紧。Typora对LaTeX公式支持做得很好行内公式用一对美元符号包裹$Emc^2$块级公式用两对美元符号包裹并单独占一行$$ \sum_{i1}^{n} i \frac{n(n1)}{2} $$VS Code用户需要再装MarkdownMath或KaTeX相关插件才能得到同样的渲染体验Jupyter Notebook则天然支持公式渲染。如果你主要用Markdown写理工科笔记公式支持这项能力甚至应该排在编辑器选择的第一位。再来说目录。Typora里只要写一行[TOC]后面就自动长出全文档目录。Obsidian左侧自带大纲不需要额外操作。VS Code装了Markdown All in One之后可以自动收集所有标题然后插入目录。Jupyter Notebook生成Markdown目录我一般用JupyterLab自带的大纲或导出后用VS Code再补一个目录处理完的效果也很不错。3.6 Markdown语法手册下载、保存、按需查阅我不建议任何人去把Markdown语法全量背下来。日常写作中80%的格式需求只需要标题、列表、加粗、斜体、链接、图片、表格、代码块这几样真正遇到生僻需求时查询速度比记忆深度重要。你可以上网搜索“Markdown语法手册”很多开发者都整理过一份带示例的速查文档。找到心仪版本后别只看一眼就关掉下载或保存成markdown文件放进自己的笔记目录这样它本身就是一份Markdown文档既能在任意编辑器里渲染查看又能当练习素材。我自己到现在还留着CommonMark规范的关键片段遇到语法边界问题就去翻一下比凭感觉乱试强得多。4. 把Markdown接入工作流写作、笔记、博客与文档产出4.1 从笔记到成稿我的写作流程工具选得再花哨不融入日常流程都是白搭。我现在写一篇技术博客或一份方案文档流程基本固定成四步。第一步先在项目文件夹里建好两个东西一个md文件、一个assets文件夹。md文件命名为draft.md还是中文标题都无所谓关键是assets目录从一开始就存在避免写到一半插入图片时路径乱飞。第二步用编辑器打开文件先写标题骨架。这一步只写各级标题不写正文把整篇文章的脉络像提纲一样铺出来。Markdown里标题写得规范渲染出来的目录自然就好看后续阅读体验和转文档都受益。第三步按顺序往骨架里填肉。我习惯从最有把握的小节写起写完一节看一节约几百字遇到需要配图的内容就随手拖进assets目录。写初稿阶段完全不开页面预览只盯着源码写这样注意力始终集中在内容本身。第四步全文写完后再统一处理格式细节。这时候打开预览一眼扫到底调整明显不协调的地方然后导出目标格式。这里要重点提一句Markdown写作最有价值的部分就是把内容创作和版式美化彻底解耦了写完内容再处理格式比一边写一边调字号舒服太多了。4.2 Markdown转Word的几种可靠姿势虽然Markdown主打极简但现实中总有人需要Word版本给同事协作或提交评审。“Markdown转Word”也是高频搜索词我推荐几条路。方案一Typora直接导出。这也是最省事的路径文件菜单里点导出选择docx格式标题样式、图片、表格基本都会保留下来。缺点是有时公式和特殊排版需要二次微调不过应付日常已经够用。方案二VS Code加Pandoc。Pandoc是文档转换界的瑞士军刀在命令行里执行以下命令就能把Markdown转成Wordpandoc 笔记.md -o 笔记.docx这个方案灵活度更高可以自定义Word模板、样式但需要先安装Pandoc并简单配置环境变量。对程序员来说难度不大。方案三在线转换工具。适合偶尔一次的临时需求把Markdown文本粘进去点转换下载Word文件。注意别上传公司敏感文档在线转换本质上就是把数据交给第三方服务器处理。不管用哪种方案转完Word之后都建议从头到尾翻一遍。最容易出问题的是三个地方表格跨页断行、图片位置漂移、数学公式变成图片或乱码。我一般会先给自己发一份Word在手机上看一遍因为手机浏览器的排版处理逻辑和桌面版有差异能提前发现不少潜在问题。4.3 在Jupyter Notebook里用好Markdown目录与数学公式做数据分析的人绕不开Jupyter Notebook。Notebook里的每一个单元格其实都可以是Markdown你把单元格切换成Markdown写# 标题按ShiftEnter执行单元格立刻渲染成好看的标题。这意味着你可以在代码块和文字说明之间无缝切换形成一份可交互的分析报告。想生成目录JupyterLab自带大纲视图打开左侧栏找到Outline图标就能看到所有标题。如果用的是经典Jupyter Notebook可以装Jupyter Notebook extensions里的Table of Contents 2插件顶部就会出现一个目录浮层。我自己更常用的做法是写完Notebook后用命令转为Markdown再补目录。jupyter nbconvert --to markdown 分析报告.ipynb --output 导出.md然后用VS Code打开导出后的md文件用Markdown All in One生成目录。这样导出的内容脱离Jupyter环境也能正常阅读发给别人不需要对方装Python环境交互性虽然在导出后消失了但传播性大幅提升。如果你本来就打算发一份能跑的Notebook给别人那直接在JupyterLab里用大纲更方便。4.4 从Markdown到博客与知识库Markdown最大的红利在于它几乎成了静态博客和知识库的通用语言。GitHub自动渲染仓库里的README.md你写一篇说明文档别人在仓库首页就能看到排版后的内容不需要任何额外操作。博客场景里Hexo、Hugo、VuePress这些静态站点生成器都是把Markdown文件作为内容源写好source/_posts/xxx.md丢进去构建命令一跑整个站点就出来了。用这种工作流你写博客的体验可以做到和写本地笔记几乎没有区别换主题、换平台都只是换一层壳内容始终是md文件。知识管理场景中Obsidian、Logseq这类工具的底层文件也是Markdown但它们额外加入了双链、图谱等能力。这意味着你今天用Obsidian写的笔记明天迁移到其他支持Markdown的工具内容不会报废。别小看这一点很多人的笔记被封闭格式困在一个软件里想跳槽软件成本高得吓人。Markdown因为是完全开放的纯文本格式天然具备抗锁定的能力。顺便提醒一句搜索“编辑器”时会看到很多不同领域的同名工具比如字体编辑器、PDF编辑器、游戏关卡编辑器、SVG编辑器它们和Markdown编辑器完全不是一回事。搜资料时加上“Markdown语法”“md编辑器”这类限定词可以过滤掉大量无关结果。5. 常见问题与排查技巧实录5.1 高频问题速查表问题现象常见原因解决方案图片显示不出来路径错误、文件名包含中文或空格、大小写不一致改用相对路径图片统一放进assets目录文件命名避免中文和空格按回车没有换行对Markdown换行规则理解偏差段落间空一行行尾两个空格ShiftEnter软换行表格列对不齐分隔行没有写或对齐冒号写错检查第二行是否用---且竖线数量一致目录不更新编辑器插件缓存或没有安装目录插件Typora用[TOC]VS Code安装Markdown All in One预览和导出不一致不同渲染器对同一种语法支持程度不同先明确最终输出目标导出后重点检查表格、图片、公式代码块没有高亮代码块没有标注语言三个反引号后直接写语言名如pythonMarkdown All in One插件下载失败网络波动、扩展市场访问异常在VS Code扩展面板里搜索安装或离线下载VSIX文件安装数学公式显示成源码编辑器缺少公式渲染插件Typora默认支持VS Code安装MarkdownMath插件表格粘贴到Excel错位复制时把分隔行也当成了数据先导出Word或用转换工具再打开到Excel中文文件名无法生成链接URL编码问题文件名改为英文或是用URL编码后的链接地址5.2 本地组策略编辑器打不开和Markdown编辑器有关系吗这个问题在搜索“编辑器”时经常被混进来我顺便辟个谣。“本地组策略编辑器”是Windows系统自带的管理工具和Markdown编辑器完全是两个物种。它一般通过运行gpedit.msc打开如果打不开常见排查思路是用管理员身份运行命令、确认系统版本是否支持、检查相关系统组件是否完整。这些都是操作系统层面的操作不用在Markdown编辑器里找原因。我这个提醒想表达的核心观点是搜索“编辑器”的时候结果里混着太多同名软件。搜解决方案前先确认自己搜的是不是同一个工具。否则你拿着“本地组策略编辑器打不开”的搜索结果跑去Markdown编辑器配置文件里翻半天纯属浪费时间。5.3 我的几个踩坑实录这里分享几个我真实遇到过的坑都是不起眼的细节但每一个都让我折腾过不少时间。第一个坑图片文件名里有空格。以前我习惯把截图命名为“微信截图 2025-06-01.png”在Typora里本地预览没问题但提交到博客或发给别人之后图片就裂了。原因就是某些渲染引擎不会自动处理空格要把空格处理成%20或者干脆重命名。现在我所有素材都强制用小写英文加短横线命名基本零问题。第二个坑表格单元格里我手滑写了竖线。比如内容里带“A/B”没问题但如果内容是“操作|结果”这种包含竖线的文字表格会直接错位。解决办法是把单元格里的竖线用转义符号处理写成\|这样就不会被当成表格分隔符了。第三个坑依赖本地绝对路径插入图片。以前图省事直接复制了图片的完整路径粘贴进Markdown当时预览一切正常。等我把整个文档目录拷到另一台电脑图片全都找不到了。从那以后我严格执行“每个项目一个assets目录、图片都用相对路径”的规范再也没有翻过车。第四个坑以为装了Markdown Preview Mermaid Support就能在所有导出格式里展示流程图。其实不同导出工具的渲染引擎不一样有的预览支持流程图导出的PDF和Word却不支持。所以在写流程类内容时我会先确认最终输出目标如果目标是Word我就直接用表格或列表描述流程不做无谓的图表尝试。写到最后的一点个人体会写到这里我想认真说一句Markdown真正改变我的不是省了多少排版时间而是改变了写作的思考方式。以前用Word时写一段文字会不自觉地被行距、字号、缩进干扰现在用Markdown只要把#、**、-这些标记敲对结构自然浮现我能把全部力气花在“这句话到底怎么说更清楚”上。这个转变让我写文章的速度至少快了一倍质量反而更稳定。最后再分享一个小技巧还是从“欢迎使用Markdown编辑器”说起。下次你在任何编辑器里看到这行默认标题别急着删除试着把它当成一份五分钟练习素材。把示例里的每一行语法都亲手敲一遍改一改删一删再切到预览看看变化。我在带新人时把这个方法叫“跟默认文档死磕一遍”至今没发现哪个认真做完这一步的人还学不会Markdown的。语法这东西动手十分钟比阅读十篇教程都有效。
Markdown编辑器入门：语法要点、工具选型与工作流实践
我第一次认真对待Markdown是因为在GitHub上一份README。当时觉得奇怪明明就是纯文本怎么渲染出来像一篇排版工整的文档后来我才知道这类文件背后用的就是Markdown标记语言而我一直在琢磨的那个“编辑器”其实只是它的一层外壳。很多Markdown编辑器首次打开时都会给你一份默认示例文档标题就叫“欢迎使用Markdown编辑器”这句话对新手来说真的挺友好它没有让你去背语法而是让你先敲几个符号再切到预览看看发生了什么。这篇东西我不想写成干巴巴的语法手册而是想从一个实际使用者的角度把Markdown编辑器的选型、语法细节、常见坑位、工作流衔接一次讲清楚。你可能是刚下载了一个Markdown编辑器、正准备抄起键盘学语法的纯新手也可能是被图片路径失效、换行不生效折磨过一轮的进阶用户看完这篇应该都不会亏。1. 先搞清楚Markdown到底是什么和普通编辑器差在哪1.1 Markdown不是“编辑器”而是一套标记语言这里先纠正一个高频误区很多人搜“Markdown编辑器”时默认Markdown是个软件其实它是一种轻量级标记语言和HTML、LaTeX算远房亲戚只不过设计目标特别纯粹让写作者用纯文本表达结构而且表达方式接近自然语言。你打开记事本也叫编辑器打开VS Code也叫编辑器打开Word也能管它叫编辑器。但“Markdown编辑器”指的是“能理解Markdown语法并把它渲染成好看格式”的那类工具。这里面牵扯到另一个经常被搜索的词编译器和编辑器的区别。传统意义上的编译器是把高级语言翻译成机器码的程序比如GCC编译C代码而Markdown的转换过程更像“排版引擎”它把# 标题这种轻量标记翻译成HTML、PDF、Word等格式中间不需要生成可执行文件所以我们一般不叫它编译叫渲染叫解析。理解这一点非常关键。它会直接影响你使用Markdown的方式你不是在排版而是在写结构化的纯文本排版的事交给渲染引擎。你用**加粗**标出一段重点预览时看见加粗了那是渲染器做了它该做的事导出成PDF发现字体不太对那不是Markdown的问题是你选用的导出工具渲染能力有限。1.2 为什么用Markdown写作它解决了哪些痛点这个问题如果不去实际用光听人安利是感受不到的。拿Word对比一下写一份五页文档你可能要反复调整标题字体、行距、列表缩进、图片居中一份文档改十遍版式都不稀奇。但用Markdown写作你从头到尾只关心一件事内容有没有表达清楚。标题大小用几个#控制列表层级用缩进和符号控制加粗斜体就包两个星号这些规则一旦形成肌肉记忆写起来真的像飞一样。Markdown还有一个被低估的巨大优势纯文本格式对版本管理极度友好。你写一份技术方案想用Git做版本追踪Word文档二进制格式会让diff变成天书而Markdown文件本身是文本每一行的改动都清清楚楚。做知识管理的人更懂这个痛点Obsidian、Logseq这类工具把整库笔记做成md文件配合坚果云或Git同步数据永远不会被某个私有格式锁死。跨平台迁移就更不用说了Windows、macOS、Linux、手机端随便哪个平台都能读能写。1.3 你其实不一定要单独安装一个“Markdown编辑器”这里有个反直觉的建议如果只是想体验一下完全不用急着下载软件。GitHub上编辑README后台自带Markdown编辑器语雀、知乎、掘金这些平台写文章时也直接支持Markdown语法Jupyter Notebook里写分析报告单元格切到Markdown就能用。你完全可以在这些现成的框里先写出感觉确定离不开了再考虑安装专门的Markdown编辑器。但如果你准备长期用来写博客、记笔记、维护项目文档那确实值得花点时间挑一个趁手的工具。下面我从本地写作、程序员场景、在线轻量三个维度结合“Markdown编辑器推荐”时高频出现的几款工具说说我自己的选型思路。2. 工具选型从“欢迎使用Markdown编辑器”开始的实践路线2.1 想要快速体验先打开自带的示例文档不管你是装了Typora、Obsidian还是VS Code插件第一次新建文件多半会看到“欢迎使用Markdown编辑器”这份默认文档。别再把它当废纸一样删掉了这其实是一份精心设计的入门素材里面通常已经写好了标题、加粗、斜体、列表、链接、图片、代码块的示例。我的建议是打开示例文档之后什么都别配置先把每个示例改动一下比如把标题文字改成自己的名字把链接换成自己常逛的网站把图片路径换成本地一张真实照片。改一个看一次预览效果强迫自己理解“源码”和“渲染结果”之间的对应关系。这个过程用不了二十分钟但比背十页语法手册管用得多。2.2 本地写作派Typora、Obsidian、Joplin怎么选如果你明确知道自己要拿Markdown做什么选型其实就清晰了。工具核心定位优点可能要注意的点Typora纯粹的Markdown写作工具沉浸式写作“所见即所得”的体验最自然导出PDF、Word、HTML都很方便早期版本免费后续版本需要付费授权Obsidian本地知识库双链、图谱、插件生态特别丰富所有笔记都是本地md文件隐私性很好上手有点门槛插件太多容易陷入折腾插件而不是写笔记的状态Joplin开源笔记应用免费开源支持端到端加密同步笔记和待办事务整合得不错编辑器本身比Typora朴素一点如果你是博客作者、要写技术文档我建议优先试Typora它的编辑器体验是三家里面最“干净”的。如果你打算搭一个长期使用的个人知识库Obsidian更合适因为它的网状笔记能力不是普通Markdown编辑器能比的。如果你对开源和隐私同步有硬性要求Joplin是稳妥的小众选择。2.3 程序员与极客VS Code Markdown插件程序员大部分时间其实就在代码编辑器里泡着如果只是写写README、整理技术笔记完全可以不切换到独立软件直接用VS Code就能把Markdown玩得很转。VS Code原生已经内置了Markdown预览能力只不过很多人不知道快捷键而已CtrlK V是侧边打开预览CtrlShiftV是整屏预览。要让写作体验再上一个台阶我推荐几个VS Code插件Markdown All in One自动生成目录、格式化表格、快速插入链接图片功能很全。Markdown Preview Mermaid Support给预览加上流程图支持装完之后写图表也能实时预览。Paste Image截图后直接粘贴插件自动把图片保存到指定目录并把相对路径写进md文件。markdownlint像代码检查工具一样提示格式问题帮你培养规范的Markdown写作习惯。顺带一提除了VS CodeVim、Zed、甚至手机上的Acode这类编辑器也有对应的Markdown支持方案。但新手真的没必要追求这些大部分需求用VS Code就够顶很久了。2.4 纯在线与轻量方案什么时候不需要装软件我也有一类场景是懒得开本地软件的只想临时把一段文本整理成Markdown格式或者从网页上摘录点内容。这时候在线编辑器就方便了代表性的有Dillinger、StackEdit这类打开网页就能写写完导出或复制走。网页内容剪藏也可以考虑MarkDownload这类浏览器扩展能把网页正文直接存成md文件非常利于收集写作素材。但用在线工具要注意两件事第一重要内容及时下载到本地不要只存在某个第三方页面里网站打不开或维护的时候你就傻眼了第二包含敏感信息的文本不要放上去在线编辑的数据始终在别人服务器上这个边界要清醒。搜索“Markdown编辑器下载”时我也建议大家认准官网或官方应用商店优先选有明确维护团队的工具。这个圈子因为开源生态繁杂出现过不少打着“Markdown编辑器”名义捆绑安装包的坑货装完编辑器电脑上多出一堆全家桶真的得不偿失。3. 核心语法与高频操作照着抄就能上手3.1 常用语法速记表下面这份表我建议你截图保存或复制进自己的笔记。能用Markdown写文档的人不是因为他记住了所有语法而是他面前有一张够用的速查表。用法写法示例渲染效果说明标题# 一级标题、## 二级标题最多支持六级标题井号后面记得有空格加粗**加粗**两个星号包裹斜体*斜体*一个星号包裹删除线~~已删除~~两个波浪线包裹引用 引用内容前面加大于号无序列表- 列表项减号、加号、星号都可以有序列表1. 第一项数字加英文句点加空格行内代码代码反引号包裹代码块python三个反引号可标注语言实现高亮分割线---三个或以上的减号链接[文字](网址)方括号包文字括号包地址图片在链接语法前多加一个英文感叹号3.2 换行与段落为什么按了回车还是没换行这是被问得最多的问题没有之一。Markdown里的换行规则和Word非常不一样普通按一次回车在很多Markdown引擎里只会当作一个空格并不会另起一行。真正起新段落需要在两段文字之间空一行。比如下面这种写法在渲染后两个字可能会挤在一起第一行 第二行常规的解决办法有三个第一种是段落之间加空行这是最标准、最推荐的第二种是行尾敲两个空格再回车相当于“软换行”渲染结果里会换行但不会产生段落间距第三种是直接写一个br标签这是HTML的行内换行标签在Markdown里是合法的。现在的编辑器大多也支持ShiftEnter直接软换行Typora、Obsidian都这样处理用起来非常顺手。顺便说一句有人以为表格里换行很麻烦其实表格单元格里插入br标签是最常见的做法比用空格硬撑省心得多。3.3 图片路径为什么图片总是显示不出来图片问题在热搜词里占了很大篇幅我索性把该说的都说透。Markdown里图片语法很简单方括号里的内容是“替代文字”图片加载失败时显示的就是这段文字括号里的路径才是真正的关键分为三种情况网络图片直接填URL比如。前提是这张图能正常访问。我建议你先在浏览器里打开一遍这个URL如果浏览器都打不开编辑器里自然也可能加载不了。本地绝对路径比如C:/Users/me/Pictures/a.png或/Users/me/Pictures/a.png。这种写法只在你现在的电脑上有效文件一旦换目录、换电脑路径就失效了。本地相对路径比如assets/a.png意思是“当前md文件所在目录下assets文件夹里找a.png”。这是我最推荐的写法。实际操作里每个写作项目我都建议搭配一个assets目录结构如下我的文档/ ├── 笔记.md └── assets/ ├── 截图1.png └── 截图2.jpg然后在笔记.md里这样引用这样整个文件夹拷给别人、推上Git仓库图片都不会丢。Typora可以在偏好设置里设置“插入图片时复制到指定路径”勾选后你直接拖图片进来它会自动帮你存到assets目录并生成相对路径。VS Code装了Paste Image插件后粘贴截图的体验类似。我在实际使用中还踩过一个经典的坑图片文件名包含空格和中文。一部分渲染引擎会自动转义一部分不会结果就是别人电脑上显示正常、你这边裂图。最稳的办法是文件命名从一开始就别带空格和中文用2025-06-demo-01.png这种风格一劳永逸。3.4 超链接标签和图片标签看起来像但完全不一样有人老把超链接标签和图片标签搞混我理解因为它们的语法结构确实只有一字之差。超链接写法是[文字](地址)图片写法是区别就是图片语法多了一个英文感叹号。这个感叹号千万别漏漏了渲染出来的效果就完全错了原本想放图的地方会变成一个可点击的文字链接点击后浏览器还打不开图片地址。我见过有人排查半天最后发现就是差一个!这种低级错误真的很搞心态。图片还能套进链接里生成一个“点图片跳转”的效果语法是把图片当作链接文字[](跳转链接)这种写法在博客里很常见比如点击封面图进入正文页背后就是这一段嵌套语法。3.5 表格、数学公式与目录文档档次唰地一下上去了基础语法练熟之后想让文档显得专业接下来值得学的是三件套表格、数学公式、目录。表格语法的骨架是竖线加短横线。第一行是表头第二行是分隔行分隔行里的冒号控制对齐方式---代表左对齐:--:代表居中对齐--:代表右对齐。示例| 姓名 | 年龄 | 城市 | |:---|:---:|---:| | 张三 | 25 | 上海 | | 李四 | 30 | 北京 |有人问表格怎么快速转换成Excel最暴力的方法是把Markdown表格粘贴进Typora预览再从预览里复制粘贴到Excel表格结构基本能保留。如果手头只有纯文本可以用在线“Markdown表格转换Excel”工具或者用Python的pandas去读HTML表格但不建议为了转一次表格写一堆代码性价比不高。数学公式的体验则跟编辑器绑得很紧。Typora对LaTeX公式支持做得很好行内公式用一对美元符号包裹$Emc^2$块级公式用两对美元符号包裹并单独占一行$$ \sum_{i1}^{n} i \frac{n(n1)}{2} $$VS Code用户需要再装MarkdownMath或KaTeX相关插件才能得到同样的渲染体验Jupyter Notebook则天然支持公式渲染。如果你主要用Markdown写理工科笔记公式支持这项能力甚至应该排在编辑器选择的第一位。再来说目录。Typora里只要写一行[TOC]后面就自动长出全文档目录。Obsidian左侧自带大纲不需要额外操作。VS Code装了Markdown All in One之后可以自动收集所有标题然后插入目录。Jupyter Notebook生成Markdown目录我一般用JupyterLab自带的大纲或导出后用VS Code再补一个目录处理完的效果也很不错。3.6 Markdown语法手册下载、保存、按需查阅我不建议任何人去把Markdown语法全量背下来。日常写作中80%的格式需求只需要标题、列表、加粗、斜体、链接、图片、表格、代码块这几样真正遇到生僻需求时查询速度比记忆深度重要。你可以上网搜索“Markdown语法手册”很多开发者都整理过一份带示例的速查文档。找到心仪版本后别只看一眼就关掉下载或保存成markdown文件放进自己的笔记目录这样它本身就是一份Markdown文档既能在任意编辑器里渲染查看又能当练习素材。我自己到现在还留着CommonMark规范的关键片段遇到语法边界问题就去翻一下比凭感觉乱试强得多。4. 把Markdown接入工作流写作、笔记、博客与文档产出4.1 从笔记到成稿我的写作流程工具选得再花哨不融入日常流程都是白搭。我现在写一篇技术博客或一份方案文档流程基本固定成四步。第一步先在项目文件夹里建好两个东西一个md文件、一个assets文件夹。md文件命名为draft.md还是中文标题都无所谓关键是assets目录从一开始就存在避免写到一半插入图片时路径乱飞。第二步用编辑器打开文件先写标题骨架。这一步只写各级标题不写正文把整篇文章的脉络像提纲一样铺出来。Markdown里标题写得规范渲染出来的目录自然就好看后续阅读体验和转文档都受益。第三步按顺序往骨架里填肉。我习惯从最有把握的小节写起写完一节看一节约几百字遇到需要配图的内容就随手拖进assets目录。写初稿阶段完全不开页面预览只盯着源码写这样注意力始终集中在内容本身。第四步全文写完后再统一处理格式细节。这时候打开预览一眼扫到底调整明显不协调的地方然后导出目标格式。这里要重点提一句Markdown写作最有价值的部分就是把内容创作和版式美化彻底解耦了写完内容再处理格式比一边写一边调字号舒服太多了。4.2 Markdown转Word的几种可靠姿势虽然Markdown主打极简但现实中总有人需要Word版本给同事协作或提交评审。“Markdown转Word”也是高频搜索词我推荐几条路。方案一Typora直接导出。这也是最省事的路径文件菜单里点导出选择docx格式标题样式、图片、表格基本都会保留下来。缺点是有时公式和特殊排版需要二次微调不过应付日常已经够用。方案二VS Code加Pandoc。Pandoc是文档转换界的瑞士军刀在命令行里执行以下命令就能把Markdown转成Wordpandoc 笔记.md -o 笔记.docx这个方案灵活度更高可以自定义Word模板、样式但需要先安装Pandoc并简单配置环境变量。对程序员来说难度不大。方案三在线转换工具。适合偶尔一次的临时需求把Markdown文本粘进去点转换下载Word文件。注意别上传公司敏感文档在线转换本质上就是把数据交给第三方服务器处理。不管用哪种方案转完Word之后都建议从头到尾翻一遍。最容易出问题的是三个地方表格跨页断行、图片位置漂移、数学公式变成图片或乱码。我一般会先给自己发一份Word在手机上看一遍因为手机浏览器的排版处理逻辑和桌面版有差异能提前发现不少潜在问题。4.3 在Jupyter Notebook里用好Markdown目录与数学公式做数据分析的人绕不开Jupyter Notebook。Notebook里的每一个单元格其实都可以是Markdown你把单元格切换成Markdown写# 标题按ShiftEnter执行单元格立刻渲染成好看的标题。这意味着你可以在代码块和文字说明之间无缝切换形成一份可交互的分析报告。想生成目录JupyterLab自带大纲视图打开左侧栏找到Outline图标就能看到所有标题。如果用的是经典Jupyter Notebook可以装Jupyter Notebook extensions里的Table of Contents 2插件顶部就会出现一个目录浮层。我自己更常用的做法是写完Notebook后用命令转为Markdown再补目录。jupyter nbconvert --to markdown 分析报告.ipynb --output 导出.md然后用VS Code打开导出后的md文件用Markdown All in One生成目录。这样导出的内容脱离Jupyter环境也能正常阅读发给别人不需要对方装Python环境交互性虽然在导出后消失了但传播性大幅提升。如果你本来就打算发一份能跑的Notebook给别人那直接在JupyterLab里用大纲更方便。4.4 从Markdown到博客与知识库Markdown最大的红利在于它几乎成了静态博客和知识库的通用语言。GitHub自动渲染仓库里的README.md你写一篇说明文档别人在仓库首页就能看到排版后的内容不需要任何额外操作。博客场景里Hexo、Hugo、VuePress这些静态站点生成器都是把Markdown文件作为内容源写好source/_posts/xxx.md丢进去构建命令一跑整个站点就出来了。用这种工作流你写博客的体验可以做到和写本地笔记几乎没有区别换主题、换平台都只是换一层壳内容始终是md文件。知识管理场景中Obsidian、Logseq这类工具的底层文件也是Markdown但它们额外加入了双链、图谱等能力。这意味着你今天用Obsidian写的笔记明天迁移到其他支持Markdown的工具内容不会报废。别小看这一点很多人的笔记被封闭格式困在一个软件里想跳槽软件成本高得吓人。Markdown因为是完全开放的纯文本格式天然具备抗锁定的能力。顺便提醒一句搜索“编辑器”时会看到很多不同领域的同名工具比如字体编辑器、PDF编辑器、游戏关卡编辑器、SVG编辑器它们和Markdown编辑器完全不是一回事。搜资料时加上“Markdown语法”“md编辑器”这类限定词可以过滤掉大量无关结果。5. 常见问题与排查技巧实录5.1 高频问题速查表问题现象常见原因解决方案图片显示不出来路径错误、文件名包含中文或空格、大小写不一致改用相对路径图片统一放进assets目录文件命名避免中文和空格按回车没有换行对Markdown换行规则理解偏差段落间空一行行尾两个空格ShiftEnter软换行表格列对不齐分隔行没有写或对齐冒号写错检查第二行是否用---且竖线数量一致目录不更新编辑器插件缓存或没有安装目录插件Typora用[TOC]VS Code安装Markdown All in One预览和导出不一致不同渲染器对同一种语法支持程度不同先明确最终输出目标导出后重点检查表格、图片、公式代码块没有高亮代码块没有标注语言三个反引号后直接写语言名如pythonMarkdown All in One插件下载失败网络波动、扩展市场访问异常在VS Code扩展面板里搜索安装或离线下载VSIX文件安装数学公式显示成源码编辑器缺少公式渲染插件Typora默认支持VS Code安装MarkdownMath插件表格粘贴到Excel错位复制时把分隔行也当成了数据先导出Word或用转换工具再打开到Excel中文文件名无法生成链接URL编码问题文件名改为英文或是用URL编码后的链接地址5.2 本地组策略编辑器打不开和Markdown编辑器有关系吗这个问题在搜索“编辑器”时经常被混进来我顺便辟个谣。“本地组策略编辑器”是Windows系统自带的管理工具和Markdown编辑器完全是两个物种。它一般通过运行gpedit.msc打开如果打不开常见排查思路是用管理员身份运行命令、确认系统版本是否支持、检查相关系统组件是否完整。这些都是操作系统层面的操作不用在Markdown编辑器里找原因。我这个提醒想表达的核心观点是搜索“编辑器”的时候结果里混着太多同名软件。搜解决方案前先确认自己搜的是不是同一个工具。否则你拿着“本地组策略编辑器打不开”的搜索结果跑去Markdown编辑器配置文件里翻半天纯属浪费时间。5.3 我的几个踩坑实录这里分享几个我真实遇到过的坑都是不起眼的细节但每一个都让我折腾过不少时间。第一个坑图片文件名里有空格。以前我习惯把截图命名为“微信截图 2025-06-01.png”在Typora里本地预览没问题但提交到博客或发给别人之后图片就裂了。原因就是某些渲染引擎不会自动处理空格要把空格处理成%20或者干脆重命名。现在我所有素材都强制用小写英文加短横线命名基本零问题。第二个坑表格单元格里我手滑写了竖线。比如内容里带“A/B”没问题但如果内容是“操作|结果”这种包含竖线的文字表格会直接错位。解决办法是把单元格里的竖线用转义符号处理写成\|这样就不会被当成表格分隔符了。第三个坑依赖本地绝对路径插入图片。以前图省事直接复制了图片的完整路径粘贴进Markdown当时预览一切正常。等我把整个文档目录拷到另一台电脑图片全都找不到了。从那以后我严格执行“每个项目一个assets目录、图片都用相对路径”的规范再也没有翻过车。第四个坑以为装了Markdown Preview Mermaid Support就能在所有导出格式里展示流程图。其实不同导出工具的渲染引擎不一样有的预览支持流程图导出的PDF和Word却不支持。所以在写流程类内容时我会先确认最终输出目标如果目标是Word我就直接用表格或列表描述流程不做无谓的图表尝试。写到最后的一点个人体会写到这里我想认真说一句Markdown真正改变我的不是省了多少排版时间而是改变了写作的思考方式。以前用Word时写一段文字会不自觉地被行距、字号、缩进干扰现在用Markdown只要把#、**、-这些标记敲对结构自然浮现我能把全部力气花在“这句话到底怎么说更清楚”上。这个转变让我写文章的速度至少快了一倍质量反而更稳定。最后再分享一个小技巧还是从“欢迎使用Markdown编辑器”说起。下次你在任何编辑器里看到这行默认标题别急着删除试着把它当成一份五分钟练习素材。把示例里的每一行语法都亲手敲一遍改一改删一删再切到预览看看变化。我在带新人时把这个方法叫“跟默认文档死磕一遍”至今没发现哪个认真做完这一步的人还学不会Markdown的。语法这东西动手十分钟比阅读十篇教程都有效。
