Markdown 这个工具，已经成了很多文字工作者绕不开的基础设施。写技术文档、记笔记、维护项目 README、甚至日常划水整点结构化内容，都会碰到它。但我发现一个现象：大部分人嘴上说“会用 Markdown”，实际只是记住了#和*，一旦遇到换行、表格复制、公式、导出 PDF 乱码、VSCode 里看不到目录这类问题，照样卡壳。这篇就来梳理一下 Markdown 的常规用法，同时把大家在搜索里反复问的那些细节坑一并捋清楚，保证你读完能直接落地。
先说这篇文章适合谁。如果你是刚接触 Markdown 的新手，可以把它当成一张完整的地图，从标题、列表、代码块这些基础语法一路看到 VSCode 环境搭建，少走弯路；如果你已经写了一阵子，也可以重点看后面的“常见问题与排查技巧实录”，那些都是实操里高频出现、文档里又不会细写的场景。
1. 为什么劝你把 Markdown 当默认写作工具
现在笔记软件五花八门，各种富文本排版的编辑器也很多，为什么还是建议你把 Markdown 作为默认写作格式？我自己的体会是，它解决了一个最核心的痛点：内容与样式分离。你用#标记标题，用>标记引用，用 ``` 标记代码块，文章的结构是语义化的，而不是靠“选中文字然后点一下字号按钮”这种物理方式。
这种语义化思维一旦建立起来，跨平台迁移就特别轻松。今天在 VSCode 里写，明天拿到网页端编辑器里继续，后天再用笔记软件导入，只要对方支持 Markdown 渲染，排版基本不会乱。反过来，如果你把内容存在某个私有格式里，将来不续费或者想换工具，迁移一次就能烦到怀疑人生。
另外还有一个关键优点：纯文本可读。哪怕渲染引擎挂了，打开.md文件看到的仍然是层次分明、加粗和链接都带标记的文本，不会变成一堆乱码。而且拿给 ChatGPT 这类大语言模型处理时，Markdown 结构能帮它更好地理解文档重点层级，这就是现在不少工作流里“Markdown 格式 LLM 接收”会成为热词的原因。
从长远看，学 Markdown 的成本极低。全部语法一天内基本能过一遍，真正值钱的是习惯养成。一旦写任何东西都下意识用标题层级、有序列表、引用块来组织，你会发现内容质量本身也会提升，因为你会更注意逻辑结构，而不是被字体大小和颜色牵着走。
1.1 Markdown 的“语义”比“效果”更重要
很多新手学 Markdown 时有个误区：以为#是“变大字号”的快捷键。这种理解在短期能糊弄过去，但长期一定会出问题。真正的#语义是“一级标题”，它应该被用在文档主标题或章节最小分块的地方。同一个文档里，一级标题不应该频繁出现；一级下面是二级，二级下面是三级，这种层级关系才构成文档的骨架。
这个思维还能帮你解决很多衍生问题。比如有人问“Markdown 修改标题之后没有 # 了，如何改回来”，多半就是把文本粘贴到了所见即所得模式里，或者编辑器自动把源码标记隐藏了。这时候你应该想到的是：标题结构是由标记决定的，不是由“看起来像不像标题”决定的。切回源码模式，找到那一行，补上对应层级的#，问题就解决了。
1.2 “轻量标记”不等于“不用排版”
另一个容易被忽略的点是，Markdown 也有排版约束。它刻意限制了你对字体、颜色、字号的直接控制，反而迫使你在排版时更关注逻辑而不是外观。项目列表要同级就用相同符号，嵌套要缩进；引用块里不要随便塞大段代码；表格里每一列的内容尽量简短清晰。这些限制其实是保护，让文档保持整洁。
2. 基础语法精讲与实操：从高频标记开始
如果把 Markdown 语法按使用频率排个序，标题、列表、链接、代码块、引用这几样占到了 80% 的日常需求。先把这些弄得滚瓜烂熟，比死记公式和复杂表格有用得多。
2.1 标题与列表：层级不对，读起来就累
标题写法看起来简单，但有不少人上来就翻车。标准写法是在行首加#加空格，再写标题文字。#是一级，##是二级，###是三级，最多到六级。这里面的常见错误有两个：
- 第一个是
#后面不打空格。部分渲染引擎对#abc不识别，于是你在预览里看到的就不是标题，而是一段普通文字，看起来像是“标题没有生效”。 - 第二个是跳级。比如从
##直接跳到####，中间少一级。这样目录树会出现空洞，影响阅读节奏，也不利于后续自动生成目录。
列表分无序列表和有序列表。无序列表用-、*、+都能起头，有序列表用1.、2.这种形式。我习惯统一用-，因为不同渲染器对*的兼容性偶尔有差异。嵌套列表要注意缩进，一般用两个或四个空格。一个很常见的现象是：缩进不对，原本想做子列表的内容跑到了上级列表，预览效果全乱。
引用块用>表示，和电子邮件里的引用习惯一致。引用里可以继续嵌套标题、列表、代码块，但层级过多会明显影响可读性，所以尽量控制在两层以内。
2.2 代码与行内代码：别再把代码块写成普通段落
写技术类内容就一定离不开代码。在 Markdown 里有两种代码承载方式：行内代码和代码块。假如你只是想提某个函数名，比如print，用一对反引号包起来即可。如果是一整段代码，就需要使用代码块。
最常见的代码块写法是用三个反引号包裹，并在开始位置标注语言类型实现语法高亮：
def hello(): print("Hello, Markdown!")这里有个小细节值得注意：反引号不是单引号，也不是中文引号。从聊天软件或 Word 里复制过来的引号经常会变成智能引号，导致代码块包裹失败。如果你写完发现代码没有被高亮，先检查引号是不是英文半角。
如果你的代码块里本身包含三个反引号，例如要展示怎么嵌套 Markdown，那就需要在外层使用四个反引号 ````，这样内层的三个反引号不会提前终止代码块。这个知识点不太常用，但遇到时能省下不少排查时间。
2.3 链接与图片：相对路径和绝对路径要区分
链接的常规语法是[显示文字](地址)。这个地址可以是网络 URL，也可以是本地相对路径。写技术文档时，如果图片和文档在同级目录，推荐使用相对路径，这样整个仓库目录一起迁移时图片不会挂。地址里如果包含空格，最好用尖括号包一下，或者做 URL 编码。
图片语法相当于链接前面加了一个感叹号：。替代文字很重要，既能帮助屏幕阅读器识别内容，又能在图片加载失败时告诉读者这里原本是什么。
还有一个在 VSCode 场景下很方便的技巧：如果图片在剪贴板里，可以直接粘贴到 Markdown 编辑器，配合自动保存功能，图片会被复制到本地 assets 目录，并自动插入引用语句。这正是“在 VSCode 里面使用 Markdown 要做哪些准备工作”里最值得优先配置的能力之一。
2.4 表格、公式、任务列表：进阶内容的使用边界
Markdown 原生表格并不属于最初的 John Gruber 版本的语法，但因为太实用，CommonMark 和 GFM（GitHub Flavored Markdown）等方言都支持了。表格语法长这样：
| 项目 | 语法 | 说明 |
|---|---|---|
| 加粗 | **文字** | 强调 |
| 斜体 | *文字* | 弱强调 |
很多人写表格容易对不齐，渲染倒是没问题，但源码阅读性很差。更重要的是，表格里别放长句子，否则在手机上会横向溢出。
公式在标准 Markdown 里原本不支持，后来生态里引入了 LaTeX / MathJax / KaTeX 支持，主要在学术笔记和博客场景里才算刚需。行内公式用单个美元符号包裹，如$E=mc^2$；块级公式用双美元符号包裹。这个能力是否可用，取决于你用的渲染器或编辑器是否开启了数学扩展，并不是所有平台都默认支持。
任务列表在 GFM 里用- [ ]和- [x]表示复选框，写待办清单非常好用。
3. 编辑器选型与 VSCode 环境准备实战
语法只是基本功，真正影响使用体验的是编辑器选型和环境配置。如果选错工具，你可能写了一周就弃坑了。
3.1 在线编辑器与桌面编辑器怎么选
市面上 Markdown 编辑器可以分为三类：
第一类是纯文本编辑器，比如 VSCode，需要自己安装插件或组合多种扩展来获得完整体验。优点是灵活强大，适合长期稳定写作和源码级控制。第二类是内置渲染的专用 Markdown 编辑器，比如很多博客后台自带的编辑器，上手最快，但离线能力有限。第三类是笔记类软件，比如主流笔记工具都支持 Markdown 语法，有的走所见即所得路线，有的保留源码模式。
问“有什么软件”的人，我一般给这个建议：如果只是想快速写个 README 或临时文档，直接使用支持 Markdown 的网页编辑器或笔记软件就行；如果打算把 Markdown 作为主要工作流，VSCode 是绕不开的最佳选择，因为它背后有庞大的插件生态，并且能兼顾代码、写作、自动化脚本等工作。
现在也有人提到“高颜值 markdown 编辑器”这个方向，其实核心渲染引擎都是类似的开源组件，差距主要体现在编辑体验和 UI 设计上，所以我很少为了“颜值”推荐某个软件，而是建议把数据格式掌握在自己手里。
3.2 VSCode 里的三个必备准备工作
很多人下载完 VSCode 之后就打开.md文件，结果发现就是个纯文本，完全没有任何预览和快捷键支持。这里面的原因是：VSCode 本身只内置了基础 Markdown 渲染，但很多符合中国用户习惯的增强操作需要额外配置。
我建议至少要完成以下三步准备工作。
第一步，安装 [Markdown All in One] 插件。这个插件提供了目录生成、列表编辑增强、自动格式化表格、快捷键切换标题级别等功能，安装后按Ctrl + Shift + P打开命令面板就能执行“Markdown: Create Table of Contents”这类命令。
第二步，安装 [Markdown Preview Enhanced] 插件。它最大的价值不只是实时预览，而是提供导出 PDF、HTML、Word 等多种格式的能力。它的原理是通过渲染引擎把 Markdown 转换成带样式的 HTML，再接各种后端工具输出成目标格式。热词里出现“markdown preview enhanced 使用 prince 导出乱码”就是指这个插件的高级导出功能里使用 Prince 工具时遇到编码问题，后面排查部分我会细说。
第三步，开启自动保存和剪贴板图片自动粘贴。配合 Paste Image 之类插件，写作体验能直接上一个大台阶。你从截图工具里复制图片，在 Markdown 文档里按粘贴，图片就会自动存到指定目录，并生成格式的引用。
这三步做完后，目录导航还需要一个辅助：在文件管理器里打开大纲面板。VSCode 左侧边栏有“大纲”视图，前提是你要正确使用标题层级。如果你写了#、##、###，大纲会自动列出这些层级，并支持点击跳转。很多人在 VSCode 里看不到目录，多数就是标题层级混乱或者没打开大纲视图，而不是缺插件。
4. 目录生成、文档导出与常用工作流
当文档越来越长，目录和导出就变成了刚需。尤其上班族如果愿意认真整理技术周报、研究笔记或项目方案，一定会问：怎么样能让 Markdown 转成更正式的 Word 或 PDF 格式，结构还不乱。
4.1 自动目录：长文写作的导航仪
在 Markdown All in One 中，可以在文档顶部插入<!-- TOC -->标记，插件会自动扫描标题结构，生成带锚点链接的目录。每次增加章节后可以重新运行命令来同步目录，避免手写目录越到后面越失准。
有些编辑器虽然不生成可见目录，但也会在侧边栏提供大纲。两个能力配合起来才能应付长文。我的使用习惯是：正文写完后，先检查标题层级是否有跳级。点击大纲逐一确认，如果发现####直接跟在##后面，就调整到合理的层级。这一步做完，目录基本就干净了。
4.2 导出 Word、PDF 的常用路子与乱码排查
问题最集中的环节就是导出。Markdown 本质上不是排版软件格式，所以“转 Word”天然需要中间过渡，不可能做到和 Word 原生排版完全一致。常见的三种路线：
- 路线一：Markdown → HTML → Word。先用 Markdown Preview Enhanced 渲染成带 CSS 样式的 HTML，在浏览器打开后复制到 Word 并调整样式。
- 路线二：Markdown → Pandoc → Word。用 Pandoc 可以指定参考文档模板，转换得到的 Word 文档能较好地继承标题、列表、表格样式。这是当前最推荐的路子，只要模板搭过一次，后期非常省事。
- 路线三：Markdown → PDF。又分两条支线，一条用 Playwright / Chromium 打印网页，另一条用 Prince。这里面就容易出现“使用 Prince 导出乱码”。
所谓乱码，经过排查，十有八九不是 Markdown 文件本身的问题，而是字体和编码问题。Prince 在 Linux 或 macOS 上如果没有安装中文字体，或 HTML 模板里没有声明lang="zh-CN"，导出中文时就会变成豆腐块或乱码。解决办法很简单：先确认导出环境里存在可用的中文字体，再在自定义 CSS 里显式指定字体族，比如font-family: "PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;。通过 Chrome 打印成 PDF 通常不会遇到这类问题，因为它自动调用了系统字体库。
如果你希望把这套转 Word 的工作流自动化，甚至可以结合 Coze 或者脚本工具来搭建管道：把 Markdown 文档上传，触发转换函数，下载结果文件。很多平台讨论的“markdown 转 word 工作流 coze”就是这个思路。这样做的好处是，一次配置，以后交付周报或规范化文件时能免去手动排版的时间。
5. 常见问题与排查技巧实录
这一节，我把搜索热词里大家问得最多的问题集中做一次排查实录。你可以把它当成速查表，遇到对应症状直接翻到这里。
5.1 为什么复制表格到 Word 里全乱了
Markdown 表格在渲染器里显示得很好，但当你选中预览内容然后直接粘贴到 Word，往往发现表格列宽错乱，甚至合并到一个单元格里。原因是预览渲染出的 HTML 表格结构和 Word 期望的表格结构存在兼容问题，而且 CSS 类名会丢失。
比较稳的方案：使用 Pandoc 转换，让 Word 直接生成原生表格，而不是通过复制粘贴。如果你用的渲染器支持导出 HTML，也可以在浏览器里先打开 HTML 文件，用 Word 打开 HTML，而不是玩剪贴板粘贴。还有一个小技巧，在 Markdown 里写表格时尽量别用复杂的合并行列语法，因为 GFM 方言本身就不支持单元格合并，强行加标签只会让转换工具产生更奇怪的结果。
5.2 Markdown 预览里 Mermaid 不渲染，问题出在哪
Mermaid 是一个用文本绘制流程图和时序图的开源工具，很多 Markdown 渲染器通过某种方式集成它。你满心期待地写了一个流程图，结果预览里还是代码块，没有任何图形。这通常意味着当前编辑器或渲染器没有加载 Mermaid 的 JS 库。
在 VSCode 里使用 Markdown Preview Enhanced 时，需要确认配置里启用了 Mermaid 支持，并且安装插件后重启过一次编辑器。如果是在网页平台上使用的 Markdown，要先看平台是否声明支持 Mermaid。大部分支持性说明里都会写到“支持 Mermaid 图表”，如果没写，基本就是不支持，换平台再测通常能解决。
一个容易忽略的细节：Mermaid 版本和语法之间也有兼容差异。老版本不识别新的流程图节点标记，或者某个主题命名不兼容，都可能导致渲染为空或报错。排查时可以打开浏览器的开发者工具控制台，看有没有红色报错信息，往往能直接定位到底是不是 Mermaid 解析失败。
5.3 某些软件里粘贴或导入 Markdown 后标题前的 # 不见了
这个现象在所见即所得类编辑器里尤其常见。它的内部实现会把源码标记隐藏，你眼睛看到的是渲染后的标题样式，但你在光标所在处看不到###这样的原始标记。很多人就以为自己的 Markdown 文本损坏了，拼命去“找回 #”，实际上只要找到源码模式或 Markdown 源码入口，标记一直都在。
具体操作要看软件。如果是在浏览器端的富文本编辑器里，可以查找“切换为 Markdown”或“源码模式”按钮，或者用快捷键切到源码层，找到对应标题行改成#开头的文本。如果你是从聊天软件或 Office 文档把内容直接粘贴到 Markdown 编辑器里，粘贴行为很可能已经将纯文本转成了富文本，标题标记自然就变成了“看起来像标题”的格式，而不是真正的#。这种情况需要先粘贴到纯文本中间层，比如系统自带的文本编辑器里过一道，再复制进 Markdown 编辑器，即可保留#标记。
这也解释了一个更困惑的问题：“卡叶笔记能导入 Markdown 文本吗？”答案取决于目标工具是否支持 Markdown 源码导入。如果它提供的导入功能只接收富文本，那么你需要先在自己的 Markdown 编辑器里渲染一遍，再全文复制并粘贴到目标软件中，通过剪贴板把 Rich Text 带过去。很多笔记软件支持导入 Markdown 文件后按源码模式打开，建议先去设置里找“导入 Markdown”而不是靠普通粘贴。
5.4 关于 LLM 接收 Markdown 格式的体验
现在不少人把 Markdown 工程笔记直接丢给大语言模型让它们做总结，有时会发现模型理解得不够精准。这不一定是模型能力问题，也可能是 Markdown 结构本身不够清晰。写过很多次之后，我体会到：给 LLM 使用时，同一级别的标题要明确，不要用加粗代替标题，列表不要用嵌套过深的第五层、第六层。格式越干净，模型返回的结构化结果越稳定。
所以我的建议是：当你想把 Markdown 文档当作输入源给 AI 工具处理时，先清理一下格式。保留标题层级、代码块分界、表格内容；把无意义的彩色高亮去掉。这会明显改善解析效果。各大平台日益重视 Markdown 输入，也是有它道理的——对机器来说，语义化越强，理解成本就越低。
5.5 一个忠告：别让炫技代替实用
Markdown 生态发展到现在，可玩的东西非常多：上标、下标、脚注、数学公式、自定义容器、图表甚至 HTML 混排，样样都能学。但我个人在实际操作中的体会是，绝大多数场景用不到那么复杂。倒是在日常写作中，把最基础的标题、列表、代码块、段落间距和图片路径管理做到顺手，才是真正的效率提升。如果你用 Markdown 超过三个月，偶尔可以花个周末把别人写的规范文档或开源项目 README 的源码打开，看看高手怎么组织层级和拆分模块，这种收获往往比到处搜新语法更明显。
`：模拟蓝牙适配器以驱动 Web Bluetooth 仿真)
