很多写技术文档、做项目笔记的朋友，最开始都是被 Word 和富文本编辑器里的排版折磨过：标题样式不统一、列表缩进错乱、代码高亮丢失、复制到网页后格式全乱。后来我逐步把日常记录、项目文档、甚至是博客初稿全部切到 Markdown，配合一款支持“所见即所得”的编辑器，整个写作体验提升非常明显。本文就围绕 Markdown 的核心语法、常用编辑器选型、VS Code 实操配置以及高频踩坑点展开，希望能给刚入门或想优化写作流程的朋友一份可直接落地的参考。
1. Markdown 到底是什么？为什么它能做到“所见即所得”
1.1 从纯文本标记说起
Markdown 是一种轻量级标记语言，设计目标就是“用纯文本表达文档结构”。它不会像 Word 那样把格式直接写入二进制文件，也不依赖某个特定的商业软件。你只需要用#、*、>、-这类符号，就能表达标题、加粗、引用、列表等含义。
举个例子，在普通记事本里写下这样一段内容：
# 这是一个一级标题 这里是一段普通文字，可以**加粗**，也可以 *倾斜*。当它被 Markdown 渲染器处理之后，就会变成带标题层级、加粗和斜体效果的富文本。也就是说，Markdown 的源文件是纯文本，但从阅读体验上又能通过实时渲染呈现出接近 Word 的效果。
这也是“所见即所得”在 Markdown 场景下的含义：一边写源码，一边看到渲染后的效果，而不是写完一堆符号后还要在脑海里脑补最终样式。
1.2 适用场景和常见误区
Markdown 的适用场景非常多：
- 技术文档、README、项目 Wiki；
- 个人笔记、博客、公众号草稿；
- 接口文档、需求文档、会议纪要；
- 代码仓库中的说明文档；
- 日常邮件和团队协作文档。
不过 Markdown 并不是万能的。如果你需要极其复杂的排版，比如毕业论文、带封面和页眉页脚的正式标书，Markdown 并不适合直接作为最终交付格式，建议的做法是用 Markdown 写作，再通过导出工具转成 Word 或 PDF 做最终排版。
还有一个常见误区是“Markdown 就等于 Typora，或者等于某个编辑器”。实际上 Markdown 是一种格式规范，编辑器只是工具。Typora、Obsidian、VS Code、语雀、飞书等不同软件对 Markdown 的支持程度和扩展语法都不完全一样，这也是为什么同一份.md文件在不同工具中渲染效果会有细微差异。
1.3 源码模式与渲染模式
大部分 Markdown 编辑器都支持两种视角：
一种是源码编辑模式，屏幕上显示的是带着#、*、-的原始内容；另一种是预览 / 渲染模式，屏幕上显示的是排版好的效果。
“所见即所得”型编辑器，比如 Typora，会把源码符号隐藏起来，直接以最终样式显示。例如你在源码里写了一个二级标题，编辑界面上看到的就是一个标题，而不是一行## 文字。当你移动光标到标题附近时，才会临时显示出##标记。这种设计降低了阅读负担，但对新手也产生了一个疑问：为什么标题前面的#不见了？其实它只是被编辑器临时隐藏了，不是内容丢失。
理解了这两种模式，后续遇到“标题 # 没了我怎么改回来”之类的问题时，就不会惊慌。
2. 极简 Markdown 核心语法，掌握这些就够用
2.1 标题与换行
标题是 Markdown 中最基础的元素，用#的数量表示层级。标准的写法是一级标题一个#，二级标题两个#，最多到六级。
# 一级标题 ## 二级标题 ### 三级标题需要注意两件事：
第一，#后面必须加一个空格再接标题文字，否则有些渲染器不会识别为标题。
第二，标题前后建议用空行与正文隔开，这样在 GitHub、语雀等平台渲染时更稳定。
换行是新手最容易踩坑的地方。在 Markdown 中，单纯在源码里回车，渲染后并不一定产生换行。不同渲染器对“单换行”的处理规则不完全一致，CommonMark 规范要求用两个及以上空格加回车，或者用一个空行来产生段落分隔。为了兼容绝大多数平台，我建议使用“空行分段”：
这是第一行文字。 这是第三行文字，中间通过空行实现了分段。如果就是想在同一段落内强制换行，可以在行尾敲两个空格再回车。不过在多数所见即所得编辑器中，直接按 Enter 和 Shift + Enter 就能区分段落与换行，源码层面的空行规则了解即可。
2.2 强调、列表与引用
强调语法包括加粗和斜体：
**这是加粗** *这是斜体* ***这是加粗又斜体***列表分为无序列表和有序列表：
- 无序列表项 - 无序列表项 - 嵌套列表项 1. 第一步 2. 第二步 3. 第三步引用使用>符号：
> 这是一段引用内容 > > 这是引用的第二行在博客写作中，引用块常被用来放“特别提示”“经验总结”等内容，视觉上比普通段落更醒目。
2.3 代码块与行内代码
技术写作最常用到代码。行内代码用反引号包裹：
在 Python 中可以用 `print()` 输出内容。多行代码块用三个反引号包裹，并可以注明语言类型，这样会触发语法高亮：
```python def hello(): print("Hello, Markdown!") ```这里特别建议：在写技术文档时，代码块一定要标注语言名称，比如python、java、sql、bash。这样在大多数渲染器中都能得到更漂亮的高亮效果，读者复制代码时也不会丢缩进。
2.4 链接与图片
链接语法是[文字](地址)：
[Markdown 官方教程](https://daringfireball.net/projects/markdown/)图片语法是在链接前加一个感叹号：
图片路径可以是网络 URL，也可以是本地相对路径。如果你在写一个包含图片的项目文档，推荐把图片统一放在assets/images目录下，然后在 Markdown 中按相对路径引用。这样做的好处是项目克隆到本地后，图片依然可以正常显示，不会出现“只有你能打开，别人看不到”的情况。
在支持拖拽上传的所见即所得编辑器中，你甚至不用手写图片语法，直接拖图片进来即可，编辑器会自动生成相对路径，并把图片复制到指定目录。
2.5 表格与任务列表
表格是 Markdown 中稍显复杂但也很实用的语法。基本结构如下：
| 功能 | 语法 | 说明 | | --- | --- | --- | | 加粗 | `**文字**` | 用于强调重点 | | 斜体 | `*文字*` | 用于弱化提示 | | 行内代码 | `` `代码` `` | 用于代码片段 |渲染之后会得到一个表格。需要注意：表格的---分隔行不能省略，它是列对齐和表头识别的关键。目标列可以写成:---（左对齐）、:---:（居中）、---:（右对齐），但日常写作中保持默认左对齐即可。
任务列表在 GitHub、语雀、Obsidian 中都很常见：
- [ ] 待完成事项 - [x] 已完成事项它非常适合用来管理写作大纲、开发计划或迁移任务。这里有一个小坑：部分渲染器要求任务列表与[ ]/[x]之间保留一个空格，否则不会识别为复选框。
3. 所见即所得编辑器推荐：不同人群应该怎么选
3.1 桌面端：Typora、Obsidian、MarkText
Typora 是很多人接触“所见即所得”的第一款编辑器。它把源码标记隐藏起来，整个界面非常干净，写起来像在用 Word，但又没有 Word 那些烦人的工具栏。Typora 支持主题定制、图片自动上传、导出 PDF / Word / HTML，非常适合博客写作和日常笔记。
Obsidian 则是笔记管理系统和 Markdown 编辑器的结合体。它底层基于本地纯文本文件，所有笔记都是一个.md文件，支持双向链接、标签、图谱、插件市场。如果你需要建立个人知识库，Obsidian 会是更长期的选择。
MarkText 是一款开源的 Markdown 编辑器，同样支持所见即所得和多种主题，适合偏爱开源工具、不希望依赖商业软件的用户。不过它的更新节奏相对慢一些，插件生态也不如 Obsidian 丰富。
3.2 Web 端与云端：语雀、飞书、Notion
如果是团队协作，云端文档工具会更合适。语雀对 Markdown 的支持做得比较细致，支持源码 / 所见即所得切换，也支持导入.md文件；飞书文档同样支持 Markdown 语法，输入#加空格可以快速创建标题，还支持代码块、表格、Mermaid 流程图。Notion 则偏向 All-in-One 知识管理，但它并不是严格意义上的 Markdown 编辑器，更像“支持 Markdown 语法的块编辑器”。
选型时可以遵循两个原则：
- 个人长期笔记，优先选择本地存储的编辑器，比如 Obsidian，数据更安全；
- 团队共享文档，优先选择云端协作工具，比如语雀或飞书，权限和分享更便利。
3.3 开发者向：VS Code 组合方案
VS Code 本身是一款代码编辑器，但通过插件完全可以变成强大的 Markdown 写作环境。它默认自带 Markdown 预览，配合插件后能实现目录、图表、导出、自动完成等能力。
在后面的章节中，我会重点演示如何用 VS Code 搭建一套接近“所见即所得”的 Markdown 写作环境，这套方案对熟悉命令行和配置文件的开发者尤其友好。
4. VS Code 搭建 Markdown 写作环境，完整实操
4.1 安装必要插件
打开 VS Code 的扩展面板，搜索并安装以下几个插件：
| 插件名称 | 作用 |
|---|---|
| Markdown All in One | 提供目录生成、快捷键、自动格式化等能力 |
| Markdown Preview Enhanced | 增强预览，支持导出 PDF / HTML、自定义 CSS |
| Paste Image | 粘贴图片时自动保存到指定目录并插入引用 |
| Markdown TOC | 自动生成目录，已可用上面的插件部分替代 |
安装完成后，你可以按Ctrl + Shift + P（macOS 为Cmd + Shift + P），输入Markdown: Open Preview to the Side，把源码和预览分屏显示。
4.2 配置 Markdown All in One
在 VS Code 设置中搜索并配置以下内容：
{ "markdown.extension.toc.updateOnSave": true, "markdown.extension.toc.levels": "1..3", "markdown.extension.preview.autoShowPreviewToSide": false, "markdown.extension.orderedList.marker": "one", "markdown.extension.italic.indicator": "*" }参数说明：
toc.updateOnSave：保存文件时自动更新目录；toc.levels：目录最多包含几级标题，这里配置为 1 到 3 级；orderedList.marker：有序列表数字序号模式，one表示始终显示为1.；italic.indicator：斜体使用*，避免和下划线混淆。
设置完成后，在 Markdown 文件中插入光标，按Ctrl + Shift + P，输入Markdown: Create Table of Contents，即可在光标位置生成目录。
4.3 配置 Paste Image 实现图片自动保存
写作时经常需要截屏插入图片，手动保存太麻烦。安装 Paste Image 插件后，按下Ctrl + Alt + V，剪贴板中的截图会自动保存到当前文件同级的images目录中，并自动插入：
默认文件名是一串时间戳，建议在设置里修改为更可读的命名规则：
{ "pasteImage.namePrefix": "${currentFileNameWithoutExt}_", "pasteImage.path": "${currentFileDir}/images", "pasteImage.basePath": "${currentFileDir}", "pasteImage.forceUnixStyleSeparator": true }这样截图的文件名会带上当前 Markdown 文件名前缀，后期整理图片时更容易对应。
4.4 配置 Markdown Preview Enhanced 导出和自定义样式
Markdown Preview Enhanced 是一个功能非常强的插件。它支持的导出方式包括 HTML、PDF、PNG、Word（需要 Pandoc 配合），还支持在预览中渲染 Mermaid、LaTeX 数学公式等。
在预览页面点击右键，可以找到Export相关菜单。如果你只导出 HTML，插件内置的依赖就足够；如果导出 PDF，建议通过 Chrome / Edge 打印到 PDF，这样中文和代码高亮效果是最好的。
自定义 CSS 也可以让预览更接近你想要的风格。在 Markdown Preview Enhanced 插件设置中找到Preview Theme，选择custom后，在用户设置中指定一个 CSS 文件路径：
{ "markdown-preview-enhanced.customCss": "D:/md-theme/custom.css" }CSS 示例：
body { font-family: "Microsoft YaHei", "PingFang SC", sans-serif; line-height: 1.8; max-width: 900px; margin: 0 auto; padding: 20px; } h1, h2, h3 { font-weight: 600; } pre { background: #f6f8fa; border-radius: 6px; padding: 12px; overflow: auto; }这样预览页面会按照你的字体、行距、代码块样式显示。
4.5 在 VS Code 中显示 Markdown 目录大纲
很多新手问“VS Code 中如何把 Markdown 文件的目录显示出来”，其实有两个层面：
第一，使用 VS Code 自带的“大纲”功能。点开左侧资源管理器中OUTLINE（大纲）面板，VS Code 会自动识别 Markdown 标题并展示为层级目录，点击即可跳转。
第二，使用 Markdown All in One 在文档正文中插入目录。这个目录是一段真实的 Markdown 列表，导出后依然有效，适合发布到博客或文档平台。
建议写长文档时两者配合：写作过程看大纲面板快速跳转，成稿后在大纲稳定时插入正文目录。
5. 实战：完成一篇带目录、图片、表格的 Markdown 文档
5.1 创建项目结构
我习惯用一个独立目录存放一篇长文的相关文件，结构如下：
demo-article/ ├── README.md └── images/ ├── architecture.png └── demo.png这个结构的好处是：相对路径引用图片后，整个文件夹可以整体移动、打包、上传到 Git，图片不会丢失。
5.2 编写完整文档
下面是一份示例文档，涵盖了标题、目录、段落、图片、表格、代码块等基本元素。
# 我的项目实战笔记 > 本文记录了一个小型项目的完整落地过程，包括需求分析、环境准备和核心实现。 ## 目录 - [1. 背景与需求](#1-背景与需求) - [2. 环境准备](#2-环境准备) - [3. 核心实现](#3-核心实现) ## 1. 背景与需求 日常开发中经常需要批量处理日志文件，本项目实现了一个简单的日志清洗脚本。 ## 2. 环境准备 项目依赖如下： | 软件 | 版本要求 | 说明 | | --- | --- | --- | | Python | 3.9+ | 脚本运行环境 | | pip | 最新版 | 依赖管理工具 | ## 3. 核心实现 ### 3.1 读取日志文件 ```python from pathlib import Path log_path = Path("./logs/app.log") lines = log_path.read_text(encoding="utf-8").splitlines() print(f"共读取 {len(lines)} 行")3.2 过滤异常日志
通过关键字过滤异常内容，并将结果输出到新的文件中。
### 5.3 验证渲染效果 在 VS Code 中打开这个文件，按 `Ctrl + Shift + V` 打开预览。正常情况下你应该看到： - 引用块显示为浅色背景； - 目录可以点击跳转； - 表格有边框； - Python 代码块有语法高亮； - 图片正常显示。 然后使用 Markdown All in One 自动插入目录，替换手动编写的目录列表，按保存后目录会自动更新。 ### 5.4 导出为 HTML 或 Word 如果要把文档发给同事，可以直接用 Markdown Preview Enhanced 右键导出 HTML。如果对方需要 Word 版本，建议安装 Pandoc 后执行命令： ```bash pandoc README.md -o README.docxPandoc 是一个通用文档转换工具，命令的功能是把README.md转换为README.docx。转换完成后打开 Word 检查一下表格和代码块效果，通常不会出现大问题。
6. 常见 Markdown 问题与排查思路
| 问题现象 | 常见原因 | 解决思路 |
|---|---|---|
| 换行不生效，连续两行被合成一行 | 源码中只用了单回车，没有空行或行尾空格 | 使用空行分段，或在行尾加两个空格 |
标题前面的#符号消失了 | 编辑器处于所见即所得渲染模式 | 移动光标到标题行附近即可临时显示，或切换到源码模式 |
| 图片显示为裂图 | 图片路径错误、大小写不一致、文件不存在 | 优先使用相对路径，检查文件是否存在，注意大小写 |
| 表格复制到网页后错位 | 表格缺少分隔行，列数不一致 | 增加---分隔行，保证每行列数一致 |
| VS Code 大纲不显示目录 | 标题不是标准 Markdown 标题格式 | 确认#和标题文字之间有空格 |
IDEA 中 Markdown 编辑器提示your environment does not support jcef | IDEA 内置浏览器组件依赖 JCEF，当前环境不支持 | 在 Settings 中切换 Markdown 预览方式，或安装 JetBrains 官方 Markdown 插件，或更换 JDK 环境 |
飞书文档无法渲染mermaid代码块 | 飞书文档对 Mermaid 支持有限 | 直接使用飞书自带的流程图组件，或在支持 Mermaid 的编辑器中渲染后截图 |
| Vue 项目渲染 Markdown 出现 HTML 不生效 | 缺少 Markdown 渲染库或未开启 HTML 支持 | 使用marked、markdown-it等库，并配置html选项 |
7. Markdown 进阶与工程化建议
7.1 版本管理
Markdown 文件是纯文本，天然适合 Git 管理。团队协作时，可以把文档和代码放到同一个仓库中，通过提交记录查看文档变更。这样做可以让文档评审和代码评审使用同一套流程，也方便回溯历史版本。
7.2 图片与附件规范
建议在项目根目录创建docs/assets统一存放图片，避免散落各处。图片命名尽量包含语义，例如authentication-flow.png就比img1.png更容易维护。如果你使用云端图床，也必须在 Markdown 中保留本地备份，防止图床失效后文档全面裂图。
7.3 换行与段落规范
在团队协作中，不要依赖“行尾两个空格”这种隐式换行，尽量用空行分段。这样无论同事使用 Typora、Obsidian 还是 VS Code，渲染结果都一致。如果平台支持，也可以约定源码每行不超过 80 或 120 个字符，方便在代码仓库中做 diff 审查。
7.4 表格不宜过宽
表格列数过多时，移动端阅读体验会急剧下降。建议列数控制在 5 列以内，单元格文字不要太长。如果内容确实复杂，考虑拆成多个小表，甚至改用手写列表展示。长表格在导出 PDF 时也容易出现被截断的问题。
7.5 代码块标注语言
无论代码是 Python、Java、SQL 还是 Shell，都应该在代码块顶部注明语言名。这不仅能触发语法高亮，还方便后续做全文代码片段统计。对于没有高亮需求的配置片段，可以用text或bash标注，避免渲染成乱码。
7.6 明确定义 Markdown 方言
如果团队使用语雀、飞书或 Obsidian，需要明确哪些扩展语法是允许的。比如有的平台支持高亮标记==文字==，有的不支持；有的支持 Mermaid，有的需要插件。建议在团队文档规范中限定一套“最小常用语法集”，其余能力按平台能力灵活取舍。
8. 几个值得深入的扩展方向
Markdown 的学习曲线并不长，核心语法可能一天就能掌握。真正拉开体验差距的是扩展语法和工具链：
- Mermaid 流程图：在 Markdown 中用文本描述流程图、时序图、甘特图，适合绘制架构图和技术时序图，但导出前需要在目标平台确认兼容性。
- LaTeX 数学公式：用
$包裹数学表达式，适合写算法笔记和论文草稿。 - 脚注与注释：适合长文中的补充说明，避免文章正文被解释性文字打断。
- 自定义容器：部分编辑器支持
:::tip、:::warning等提示块，可以让关键信息更醒目。 - 文档转换工作流：通过 Pandoc、md-to-docx 等工具把 Markdown 转成 Word、PDF、HTML，可以搭建出“一次编写，多渠道发布”的写作流程。
如果你已经能熟练使用基础语法，建议下一步可以学一下 Mermaid，并尝试在自己的笔记中画一个简单的组件流程图。它能很大程度扩展 Markdown 的表达边界，也让“所见即所得”不再是单纯的排版体验，而是真正的内容组织能力。
9. 给初学者的最后建议
Markdown 最大的价值不是替代 Word，而是让你把注意力从“调格式”转移到“写内容”。当你习惯了#表示标题、-表示列表、反引号表示代码之后，写作会变得非常顺畅。选择编辑器时也不用纠结太久，Typora 适合简单易用，Obsidian 适合长期知识库，VS Code 适合开发者，语雀和飞书适合团队协作。找到一款用得顺手的，坚持记录两周，你就会感受到纯文本写作带来的效率提升。如果遇到标题符号消失、图片挂掉、表格错位这类问题，回到源码模式检查一下，基本都能快速定位到原因。
