很多写技术文档、做项目笔记的朋友最开始都是被 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、MarkTextTypora 是很多人接触“所见即所得”的第一款编辑器。它把源码标记隐藏起来整个界面非常干净写起来像在用 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、自定义 CSSPaste Image粘贴图片时自动保存到指定目录并插入引用Markdown TOC自动生成目录已可用上面的插件部分替代安装完成后你可以按Ctrl Shift PmacOS 为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(encodingutf-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 jcefIDEA 内置浏览器组件依赖 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 适合开发者语雀和飞书适合团队协作。找到一款用得顺手的坚持记录两周你就会感受到纯文本写作带来的效率提升。如果遇到标题符号消失、图片挂掉、表格错位这类问题回到源码模式检查一下基本都能快速定位到原因。