大家最开始接触 Markdown多半是看到技术文档、项目 README 里的排版干净清爽或者发现同事写的笔记在 GitHub 上显示得特别漂亮。真到自己上手装环境、配编辑器、处理图片路径、导出 Word 的时候才会发现坑并不少。这篇教程不绕弯子直接讲 Markdown 的安装部署、编辑器选型、常用语法细节和几套实用的工作流全是实际操作过的经验。不论你是准备用 Markdown 写技术博客、记 Obsidian 笔记还是想把它纳入日常文档产出流程这篇文章都能省下你不少折腾的时间。我会从工具怎么选、装完怎么配、语法细节怎么用到后期怎么转换格式这条线完整走一遍顺带把网上经常搜到的换行、表格、图片路径、Mermaid 预览、目录生成这些问题一并解决掉。适合刚接触 Markdown 的新手也适合已经用了一段时间但想优化工作流的人。1. 整体思路与工具选型1.1 为什么不用 Word而要用 MarkdownMarkdown 的核心优势不在排版好看而在于它把“内容”和“呈现”分开了。你写文档的时候只需要关注结构——标题、列表、引用、代码、表格——剩下的样式问题交给渲染引擎处理。这意味着同一份.md文件在 GitHub、本地编辑器、博客系统、笔记软件里打开都能获得一致且干净的阅读体验。用 Word 写文档最常见的问题有两个一是格式混乱从网页复制内容进来字体、颜色、段落样式全乱套二是文件体积大内容还没写多少几十兆就出去了。Markdown 文件就是纯文本几个 KB 到几十 KB配合 Git 做版本管理特别方便每次改动都能看得清清楚楚。写博客的人更喜欢 Markdown因为最终发布到网页时不需要反复调整样式平台会自动渲染。还有个隐藏优势是迁移成本低。Markdown 是通用格式今天你用 Typora明天换 Obsidian后天想发布到 WordPress文件本身不需要做任何改动。相比之下Word 文档换软件打开可能排版就崩了。这点对于长时间维护知识库的人来说特别重要。1.2 编辑器选型Typora、VS Code、Obsidian 怎么选编辑器没有绝对的好坏只有适不适合你的使用场景。我三款都深度用过给你说道说道各自的脾气。Typora 是我个人最常用的它的特点是“所见即所得”左边写右边实时渲染界面干净到几乎没有干扰。LaTeX 公式、Mermaid 图表、流程图都支持导出 PDF 和 Word 的效果也比较理想。缺点是它是收费软件虽然可以一直试用但正式使用还是要买授权。如果你主要是本地写文档、导出 PDF 给别人看Typora 是最省心的选择。VS Code 适合本身就在写代码的人。装一个 Markdown All in One 插件再配一个 Markdown Preview Enhanced编辑体验完全不输 Typora。好处是免费开源插件生态丰富还能和 Git、远程服务器无缝配合。缺点是初期配置需要花点时间快捷键也需要适应对纯写作用户来说稍微有点门槛。Obsidian 更偏知识管理它把 Markdown 文件作为笔记的底层格式支持双链、标签、关系图谱配合各种社区插件可以实现非常强大的笔记流。如果你是想搭建个人知识库或者有长期积累笔记的习惯Obsidian 会是更好的选择。但它的插件配置有学习成本容易被各种玩法带偏反而不专注写作本身。1.3 在线编辑器不想安装软件时的备用方案有些人只是偶尔写一篇博客或者临时处理一份 Markdown 文档不想专门装软件那在线编辑器就是最好的选择。我常用的在线方案有 StackEdit 和 Dillinger。StackEdit 支持 Markdown 语法高亮、实时预览还能同步到 Google Drive 和 Dropbox界面是分栏式的左边写右边看效果。Dillinger 更简单打开就能写支持直接导出 HTML 和 PDF。这类在线编辑器适合应急场景但不宜作为主力工作流毕竟数据放在云端隐私和安全性都要打折扣。还有专门针对程序员场景的在线方案比如把 Markdown 直接粘贴到 GitHub 的 Issue 或者留言框里GitHub 会自动渲染。如果是快速检查语法对不对把内容丢到 GitHub 的 Gist 里预览也是很方便的的做法。2. 环境安装与编辑器配置2.1 Typora 安装配置下载、激活、偏好设置Typora 的安装本身没什么难度官网下载对应系统的安装包一路下一步就行。但装完之后的偏好设置值得认真调一轮这决定了你后面写文档的体验上限。打开 Typora 的“偏好设置”我建议重点调整几个项目。第一是“通用”里的“图像”设置默认粘贴图片进来是保存到本地文件夹但路径处理得不够智能。建议把它改成“复制图片到 ./assets 文件夹”同时勾选“优先使用相对路径”。这样你的图片会跟着文档走整个文件夹拷给别人或者传到 Git 仓库图片都不会丢。第二是“Markdown”扩展语法Typora 默认没有开启所有扩展语法比如上标、下标、高亮、脚注这些都需要手动勾选。如果发现写了语法却不生效多半是这里没开。第三是“导出”设置Typora 导出 Word 依赖 Pandoc第一次导出前会提示你安装按提示装好就能用。2.2 VS Code 搭建 Markdown 环境必备插件与快捷键VS Code 做 Markdown 编辑核心是插件组合。我试过很多套最后稳定下来的方案是三个插件少了哪个都不太顺手。第一个是 Markdown All in One。这个插件集成了自动补全、目录生成、列表自动缩进、表格格式化等功能。写 Markdown 时最常用的快捷键它都覆盖了比如加粗是CtrlB斜体是CtrlI插入链接是CtrlV直接粘贴 URL 到选中的文本上。最实用的是CtrlShiftP输入 “Create Table of Contents”直接给文档生成带锚点链接的目录。第二个是 Markdown Preview Enhanced。这个插件让预览功能大幅增强支持 KaTeX 公式、Mermaid 流程图、导出 HTML 和 PDF还支持在预览窗口右键呼出菜单做各种操作。快捷键是CtrlShiftV打开侧边预览CtrlK V是分屏预览。第三个是 Paste Image。这个插件解决的是图片粘贴问题截图后直接CtrlAltV粘贴它会自动把图片保存到指定目录并插入 Markdown 图片语法。默认配置是保存到当前文件所在目录我在设置里把它改成了${currentFileDir}/assets图片统一管理路径整洁很多。2.3 Obsidian 基础配置仓库结构、附件路径、核心插件Obsidian 的安装同样简单重点在于创建“仓库”Vault时想清楚文件夹结构。我通常建议用这样的结构笔记仓库/ ├── 00 Inbox/ # 临时收集的碎片内容 ├── 10 Projects/ # 按项目分类的文档 ├── 20 Areas/ # 长期维护的领域知识 ├── 30 Resources/ # 参考资料、摘录 ├── 90 Archive/ # 归档内容 └── assets/ # 所有附件图片、PDF等这个结构借鉴了 PARA 方法好处是内容有了明确的归属找东西不需要靠搜索。设置里需要开启“默认新附件位置”为assets文件夹这样粘贴进来的图片都会自动归拢。Obsidian 的核心插件里“大纲”和“标签面板”建议默认开启前者就是 Markdown 的标题结构对应文档目录后者方便按标签筛选内容。社区插件里我强烈推荐 Dataview它可以把笔记里的元数据比如创建日期、标签、状态自动生成表格实现类似数据库查询的效果不过这是进阶玩法刚开始用不上。3. Markdown 核心语法与高频细节3.1 基础语法速查标题、列表、引用、代码块Markdown 的基础语法网上一搜一大堆这里不把完整的语法文档抄一遍只挑高频且容易用错的来讲。标题用#到######表示六级注意#后面一定要跟一个空格否则有些渲染器不识别。列表分无序列表-或*和有序列表1.嵌套列表需要缩进两个空格或一个 Tab。引用用可以嵌套比如就是引用的引用。代码块用三个反引号包裹可以在后面标注语言类型实现语法高亮def hello(): print(Markdown code block)行内代码用单个反引号比如pip install typora。链接语法是[显示文本](URL)图片语法是区别只在一个感叹号。这些基础语法看起来简单但组合起来可以完成 90% 以上的文档写作需求。真正容易出错的反而是细节比如中英文标点混用、空格缺失、列表和段落之间的空行这些会导致渲染结果和预期不符。3.2 换行与段落的正确姿势两个空格还是空一行换行是 Markdown 新手的第一个坑。在 Markdown 里直接按一下回车换行在渲染结果中是不生效的就是说句子虽然换行了但显示出来还是连在一起的。想要真正的换行有两种做法。一是在行尾加两个空格再按回车这是 Markdown 标准语法但肉眼看不到空格经常忘记加。二是在两行文字之间空一行这样会生成一个新的段落段间距更大视觉上也更清晰。我自己的习惯是优先用空一行的方式因为两个空格在编辑时看不见回头维护的时候容易懵。Typora 有个特殊处理直接回车也能换行这是它为了所见即所得做的优化。但如果你把同一份文件放到 GitHub 或者其他编辑器里换行可能就不生效了。所以写文件时最好还是按照标准语法来不要依赖特定编辑器的“温柔”处理。3.3 表格对齐方式、复制粘贴、转换 Excel表格是 Markdown 里写起来最费劲、但又是最常用的语法。基础格式是这样的| 列1 | 列2 | 列3 | | ---- | ---- | ---- | | 内容 | 内容 | 内容 |表格的对齐方式通过第二行分隔行的冒号来控制---左对齐:---:居中---:右对齐。比如| 左对齐 | 居中 | 右对齐 | | :--- | :---: | ---: | | 1 | 2 | 3 |实际使用中我发现手写表格效率太低特别是数据多的时候。我自己的做法是如果表格数据在 Excel 里直接用在线工具把 Excel 转成 Markdown 表格或者用 VS Code 的插件格式化而不是手工一列一列敲。反过来如果想把 Markdown 表格复制到 Excel 里可以在渲染后的网页视图里选中表格直接复制粘贴到 Excel 就是规规矩矩的表格。Typora 里选中表格后右键也有 “复制为 CSV” 的选项这个配合 Excel 也很好用。3.4 图片路径与图片管理相对路径、图床、批量处理图片问题是 Markdown 工作流里最容易被忽视、后患无穷的环节。你本地写了一篇文章图片用的绝对路径比如C:\Users\me\Pictures\1.png发到博客平台上别人根本看不到。正确的做法是使用相对路径。推荐的文件组织方式是这样的docs/ ├── 文章.md └── assets/ └── 文章/ └── 1.png在文章里引用图片的路径就是assets/文章/1.png。这样整个文件夹传到 GitHub、复制给同事、放进 Obsidian 仓库图片都不会丢。Typora 和 VS Code 的 Paste Image 插件都可以配置成自动存到这个路径。还有一个思路是使用图床把图片传到云端比如 GitHub 仓库、对象存储然后在文档里引用云端 URL。好处是文档体积小、分享方便坏处是依赖网络、图床可能失效。对个人知识库来说我建议本地相对路径为主图床只用于博客文章的发布场景。3.5 特殊符号与扩展语法圈 1 到圈 19、方框、高亮、脚注中文写作里经常要打圈号数字比如①到⑲。在 Markdown 里直接输入这些符号倒是可以但有时候你会发现在某些字体下显示不出来或者复制到别的地方乱码。我的做法是用 Unicode 码直接输入① 是\u2460⑲ 是\u2472输入法里一般也直接能找到。如果要在 Markdown 里做出“方框”效果也就是任务列表语法是这样的- [ ] 待办事项 - [x] 已完成事项注意-和[ ]之间要有空格渲染后会显示为可勾选的复选框。在 GitHub 和 Obsidian 里都可以直接点击勾选做任务管理很方便。扩展语法方面Typora 支持的高亮用文字脚注用[^1]然后在文末定义[^1]: 脚注内容上标用^文字^下标用~文字~。这些语法在标准 Markdown 里不支持所以写文件时要想清楚目标渲染环境是否兼容别写完了换一个平台全乱掉。4. 进阶功能与工具链集成4.1 Mermaid 图表流程图、时序图、甘特图的 Markdown 实现Mermaid 是一个用文本描述图表的工具最大的价值是让 Markdown 文档里也能直接写流程图、时序图、甘特图。我最初接触它是为了在 GitHub README 里画架构图后来发现写技术方案、API 文档也特别有用。Mermaid 的基础用法是在代码块中标注mermaid语言然后写图表定义。比如一个简单的流程图graph TD A[开始] -- B{判断} B --|是| C[执行] B --|否| D[跳过]这里有三个核心概念要注意。第一是节点定义A[文本]表示方块节点A(文本)表示圆角节点A{文本}表示菱形判断节点。第二是连线方式--是带箭头实线---是不带箭头实线-.-是带箭头虚线是带箭头粗线。第三是子图用subgraph关键字可以把相关节点圈起来这在画复杂架构图时特别实用。VS Code 的 Markdown Preview Enhanced 和 Typora 都内置了对 Mermaid 的支持写完后在预览窗口直接可以看到渲染结果。GitHub 和 GitLab 也支持在 Markdown 文档里渲染 Mermaid 图表所以用它写技术文档完全没有兼容性问题。这份教程里就不画完整图表了结构上有需要时Mermaid 是首选方案。4.2 自动生成目录VS Code 插件与 Jupyter Notebook 场景Markdown 文档长了以后没有目录找内容确实费劲。在 VS Code 里Markdown All in One 插件提供了生成目录的快捷方式打开命令面板CtrlShiftP输入 “Create Table of Contents”它会自动扫描文档里的所有标题在光标处插入目录列表。这种目录是带锚点链接的点击就能跳转发布到 GitHub 上也能用。Jupyter Notebook 本身是用 Markdown 写文本说明的但目录支持比较弱。好在有专门的扩展解决这个问题安装 jupyter-contrib-nbextensions然后启用 Table of Contents 插件Notebook 左侧就会多出目录导航。这个方法在数据分析和机器学习项目里很实用代码多、章节多的时候有目录才能快速定位。Obsidian 不需要额外插件右上角的“大纲”面板天然就是目录而且支持实时折叠。写长文时我习惯把大纲面板打开配合标题拖动调整结构。4.3 Markdown 转 WordPandoc 工作流与 Coze 自动化把 Markdown 转成 Word 是很多人在实际工作中绕不开的需求特别是团队协作里对方只用 Word 的情况。标准解法是安装 Pandoc然后执行pandoc input.md -o output.docx这个命令会生成一个最基础的 Word 文档但样式很简陋。优化的做法是准备一个自定义的 Word 参考模板先用 Word 制作好标题字体、正文字号等样式然后导出为reference.docx之后每次转换都加上--reference-docreference.docx参数pandoc input.md -o output.docx --reference-docmy-style.docx这样生成的 Word 文档在样式上基本符合需求后续只需要微调个别格式。如果你用的是 Coze 这类自动化工作流平台可以把“Markdown 转 Word”也接进去本质逻辑是一样的先解析 Markdown 内容再调用转换工具输出 Word最后把文件发给用户。但要注意的是在线自动化工具处理复杂表格和图片路径时容易出问题最稳妥的方案还是本地安装 Pandoc。4.4 浏览器一键抓取MarkDownload 插件与 WordPress 发布有时候你在网页上看到一篇好文章想存成 Markdown 笔记手动复制粘贴再整理格式效率很低。这个场景可以用浏览器插件解决我常用的是 MarkDownload它是开源的 Markdown Web Clipper 插件支持 Chrome 和 Firefox。安装后在任意网页上点击插件图标它会自动分析网页结构把正文内容提取出来并转化成 Markdown 格式。默认配置下会保留标题、链接、图片、代码块等结构。这里有个小技巧在插件设置里开启“自动下载”配合 Obsidian 的assets文件夹可以把网页直接存进本地仓库省去手动整理的步骤。如果你用 WordPress 写博客又习惯用 Markdown 写初稿有几个方案可以实现转换。最简单的做法是安装 WordPress 的 Markdown 插件比如 Jetpack 内置的 Markdown 模块启用后可以在编辑框里直接写 Markdown发布时自动转为 HTML。另一个方案是把 Markdown 文件用 Pandoc 转成 HTML 后再粘贴到 WordPress 的文本编辑器里。前者适合日常更新后者适合批量导入。5. 常见问题与排查技巧5.1 表格在 GitHub 上显示错乱GitHub 对 Markdown 表格的语法要求比本地编辑器更严格。最容易出的问题是表格前后没有空行、表头分隔行的---数量不够、单元格里有竖线|被误解析。排查方法是检查表格前后是否各有一个空行比如上面是段落 | 列1 | 列2 | | --- | --- | | 数据 | 数据 | 下面是段落如果单元格内容本身包含|符号需要用反斜杠转义| 转义示例 | 内容 | | -------- | -------- | | 管道符 | a \| b |用 Markdown All in One 的表格格式化功能快捷键ShiftAltF可以自动修复表头对齐问题。5.2 图片路径失效显示为破损图标图片失效的原因绝大多数是路径写错了或者图片文件没有放到正确位置。排查时先确认图片文件是否真的存在于你写的路径下然后确认路径大小写是否和文件名一致最后确认用的是相对路径还是绝对路径。一个很隐蔽的问题是不同系统对路径分隔符的处理不一样。Windows 用反斜杠\但 Markdown 里反斜杠是转义字符图片路径里的\常常会被吃掉。所以 Markdown 图片路径统一应该用正斜杠/比如assets/文章/1.png即便在 Windows 下也能正常解析。另外如果发现图片在本地正常但推到 GitHub 上失效多半是 GitHub 对图片路径大小写敏感而本地文件系统不敏感。文件名是Cat.png路径写成cat.png本地能显示GitHub 上就挂了。解决方法是文件名全部用小写路径中的目录名也统一小写。5.3 VS Code 插件不生效或预览空白VS Code Markdown 插件不生效首先检查插件是否真的安装了。打开扩展面板搜索插件名确认状态是“已启用”。如果插件已安装但快捷键无效检查是否和其他插件冲突可以在键盘快捷键设置里搜命令名手动指定一个新的键位。预览空白的问题通常是预览引擎出了问题。Markdown Preview Enhanced 偶尔会缓存异常解决办法是执行CtrlShiftP输入 “Markdown Preview Enhanced: Reload Preview” 或者直接重开窗口。另一个可能是防火墙或代理设置阻止了预览引擎加载资源检查一下终端里有没有报错信息。5.4 Jupyter Notebook 无法生成目录Jupyter 的目录插件是 nbextensions如果安装了还是看不到目录按钮多半是没启用。运行jupyter nbextension enable toc2/main也可以打开 Jupyter 主页面进入 Nbextensions 标签手动勾选 Table of Contents 2。还有一类情况是JupyterLab 和经典 Notebook 的插件机制不互通在 JupyterLab 里需要安装jupyterlab/toc扩展。我遇到过用户明明用的是 JupyterLab却按经典 Notebook 的方法装插件自然没有效果。先确认你打开的是 Lab 还是经典界面。5.5 换行不生效与中英文标点混用问题换行问题在前面提过这里再补充一个典型场景在列表项内换行很多人的处理是按下回车后继续写结果渲染出来列表项被拆成了两个。- 列表项第一行 继续写的内容前面加两个空格缩进这个“继续写的内容”会作为同一个列表项的新段落显示。如果你不想缩进太多也可以使用br标签手动插入换行- 列表项第一行br 这一行紧跟在第一行下面中英文标点混用的问题更隐蔽。全角冒号和半角冒号:在 Markdown 语法里意义完全不同比如[链接文本](URL)中如果用了全角括号或冒号整个链接语法就失效了。我个人的排查经验是凡是语法不生效先检查标点符号是不是全角状态输入的。养成写 Markdown 时切换到半角标点的习惯能少踩一半的坑。6. 完整实操从零搭一套个人 Markdown 写作环境6.1 场景设定与目标假设现在你从零开始想搭建一套完整的 Markdown 写作环境需求是三端协同Windows 办公机为主力写作手机端用 Obsidian 随时记录写完后一键导出为 Word 发给同事同时能把内容同步到 GitHub Pages 作为个人博客。这套环境涉及的工具包括Typora写作主力、VS Code代码和进阶编辑、Obsidian移动端同步和知识管理、Pandoc格式转换、Git版本管理和博客发布。听起来多但实际装起来半小时内能搞定。6.2 逐步搭建流程第一步安装 Typora。官网下载 Windows 版本默认配置即可。打开偏好设置在“通用”里把图片保存路径设为./assets勾选“优先使用相对路径”。第二步安装 VS Code 和四个插件Markdown All in One、Markdown Preview Enhanced、Paste Image、Prettier。打开设置搜索pasteImage.path设为${currentFileDir}/assets。第三步安装 Git。官网下载安装包一路下一步。配置用户名和邮箱git config --global user.name yourname git config --global user.email youremailexample.com第四步安装 Pandoc。下载安装后打开终端验证pandoc --version第五步在 D 盘创建目录结构并初始化 Git 仓库mkdir -p D:/Notes/assets cd D:/Notes git init第六步手机安装 Obsidian创建仓库时选择“打开本地仓库”定位到 D 盘 Notes 目录。如果需要远程同步可以把 Notes 文件夹放到 OneDrive 或坚果云网盘里手机上同步后打开就能看到同样的内容。第七步测试完整流程。新建一个测试文档粘贴一张截图验证图片自动保存到 assets 目录。然后执行 Pandoc 转换 Word验证导出功能正常。6.3 最终效果验证完成以上步骤后写文档的流程应该是这样的打开 Typora新建文档开始写作。截图后CtrlAltV直接粘贴图片图片自动存到assets/。写完后用 Markdown All in One 生成目录如果是 VS Code 编辑。需要发 Word 时在 Typora 里文件 → 导出 → Word会自动调用 Pandoc。需要同步到手机时由于已经把 Notes 文件夹放到网盘目录Obsidian 会自动同步。需要发布到博客时用 Git 把 Notes 仓库推到 GitHub配合 Pages 服务自动渲染。这个流程的核心优势是所有内容都是纯文本 Markdown没有私有格式任何时候想换工具都可以无缝迁移。数据备份也简单把整个 Notes 目录压缩或者推到远端仓库就行。7. 写在最后的经验排版工具和技术选型说到底是服务于“更高效地写作”这件事。Markdown 的最大价值不是让你排版多漂亮而是让你能专注于内容本身在完全不思考格式的情况下产出结构清晰的文档。我踩过不少坑最有价值的一条经验是从一开始就建立规范比后期整理省力一百倍。图片统一放 assets、文件名统一小写、表格前后留空行、换行用空段落这些规范在最初会有点麻烦但坚持一个月后你会发现自己写文档的速度明显快过用 Word 的时候。还有一个建议是不要过度追求工具。我见过很多人花大量时间折腾 Obsidian 插件、自建博客主题、配置自动化工作流结果真正花在写作上的时间少得可怜。工具链够用就好Markdown 的核心语法半小时就能学会剩下的时间应该用来写内容本身。如果后续想继续扩展可以考虑的方向包括用 GitHub Actions 自动构建个人博客、把 Markdown 工作流接入思源笔记或 Notion、给 Pandoc 配置一套自己的 LaTeX 导出模板。每一个方向都有足够深的玩法但前提是一份干净、规范、不受工具绑定的 Markdown 内容库。基础打好了后续怎么扩展都行。 Markdown 全流程实战：编辑器选型、语法细节与工作流搭建
大家最开始接触 Markdown多半是看到技术文档、项目 README 里的排版干净清爽或者发现同事写的笔记在 GitHub 上显示得特别漂亮。真到自己上手装环境、配编辑器、处理图片路径、导出 Word 的时候才会发现坑并不少。这篇教程不绕弯子直接讲 Markdown 的安装部署、编辑器选型、常用语法细节和几套实用的工作流全是实际操作过的经验。不论你是准备用 Markdown 写技术博客、记 Obsidian 笔记还是想把它纳入日常文档产出流程这篇文章都能省下你不少折腾的时间。我会从工具怎么选、装完怎么配、语法细节怎么用到后期怎么转换格式这条线完整走一遍顺带把网上经常搜到的换行、表格、图片路径、Mermaid 预览、目录生成这些问题一并解决掉。适合刚接触 Markdown 的新手也适合已经用了一段时间但想优化工作流的人。1. 整体思路与工具选型1.1 为什么不用 Word而要用 MarkdownMarkdown 的核心优势不在排版好看而在于它把“内容”和“呈现”分开了。你写文档的时候只需要关注结构——标题、列表、引用、代码、表格——剩下的样式问题交给渲染引擎处理。这意味着同一份.md文件在 GitHub、本地编辑器、博客系统、笔记软件里打开都能获得一致且干净的阅读体验。用 Word 写文档最常见的问题有两个一是格式混乱从网页复制内容进来字体、颜色、段落样式全乱套二是文件体积大内容还没写多少几十兆就出去了。Markdown 文件就是纯文本几个 KB 到几十 KB配合 Git 做版本管理特别方便每次改动都能看得清清楚楚。写博客的人更喜欢 Markdown因为最终发布到网页时不需要反复调整样式平台会自动渲染。还有个隐藏优势是迁移成本低。Markdown 是通用格式今天你用 Typora明天换 Obsidian后天想发布到 WordPress文件本身不需要做任何改动。相比之下Word 文档换软件打开可能排版就崩了。这点对于长时间维护知识库的人来说特别重要。1.2 编辑器选型Typora、VS Code、Obsidian 怎么选编辑器没有绝对的好坏只有适不适合你的使用场景。我三款都深度用过给你说道说道各自的脾气。Typora 是我个人最常用的它的特点是“所见即所得”左边写右边实时渲染界面干净到几乎没有干扰。LaTeX 公式、Mermaid 图表、流程图都支持导出 PDF 和 Word 的效果也比较理想。缺点是它是收费软件虽然可以一直试用但正式使用还是要买授权。如果你主要是本地写文档、导出 PDF 给别人看Typora 是最省心的选择。VS Code 适合本身就在写代码的人。装一个 Markdown All in One 插件再配一个 Markdown Preview Enhanced编辑体验完全不输 Typora。好处是免费开源插件生态丰富还能和 Git、远程服务器无缝配合。缺点是初期配置需要花点时间快捷键也需要适应对纯写作用户来说稍微有点门槛。Obsidian 更偏知识管理它把 Markdown 文件作为笔记的底层格式支持双链、标签、关系图谱配合各种社区插件可以实现非常强大的笔记流。如果你是想搭建个人知识库或者有长期积累笔记的习惯Obsidian 会是更好的选择。但它的插件配置有学习成本容易被各种玩法带偏反而不专注写作本身。1.3 在线编辑器不想安装软件时的备用方案有些人只是偶尔写一篇博客或者临时处理一份 Markdown 文档不想专门装软件那在线编辑器就是最好的选择。我常用的在线方案有 StackEdit 和 Dillinger。StackEdit 支持 Markdown 语法高亮、实时预览还能同步到 Google Drive 和 Dropbox界面是分栏式的左边写右边看效果。Dillinger 更简单打开就能写支持直接导出 HTML 和 PDF。这类在线编辑器适合应急场景但不宜作为主力工作流毕竟数据放在云端隐私和安全性都要打折扣。还有专门针对程序员场景的在线方案比如把 Markdown 直接粘贴到 GitHub 的 Issue 或者留言框里GitHub 会自动渲染。如果是快速检查语法对不对把内容丢到 GitHub 的 Gist 里预览也是很方便的的做法。2. 环境安装与编辑器配置2.1 Typora 安装配置下载、激活、偏好设置Typora 的安装本身没什么难度官网下载对应系统的安装包一路下一步就行。但装完之后的偏好设置值得认真调一轮这决定了你后面写文档的体验上限。打开 Typora 的“偏好设置”我建议重点调整几个项目。第一是“通用”里的“图像”设置默认粘贴图片进来是保存到本地文件夹但路径处理得不够智能。建议把它改成“复制图片到 ./assets 文件夹”同时勾选“优先使用相对路径”。这样你的图片会跟着文档走整个文件夹拷给别人或者传到 Git 仓库图片都不会丢。第二是“Markdown”扩展语法Typora 默认没有开启所有扩展语法比如上标、下标、高亮、脚注这些都需要手动勾选。如果发现写了语法却不生效多半是这里没开。第三是“导出”设置Typora 导出 Word 依赖 Pandoc第一次导出前会提示你安装按提示装好就能用。2.2 VS Code 搭建 Markdown 环境必备插件与快捷键VS Code 做 Markdown 编辑核心是插件组合。我试过很多套最后稳定下来的方案是三个插件少了哪个都不太顺手。第一个是 Markdown All in One。这个插件集成了自动补全、目录生成、列表自动缩进、表格格式化等功能。写 Markdown 时最常用的快捷键它都覆盖了比如加粗是CtrlB斜体是CtrlI插入链接是CtrlV直接粘贴 URL 到选中的文本上。最实用的是CtrlShiftP输入 “Create Table of Contents”直接给文档生成带锚点链接的目录。第二个是 Markdown Preview Enhanced。这个插件让预览功能大幅增强支持 KaTeX 公式、Mermaid 流程图、导出 HTML 和 PDF还支持在预览窗口右键呼出菜单做各种操作。快捷键是CtrlShiftV打开侧边预览CtrlK V是分屏预览。第三个是 Paste Image。这个插件解决的是图片粘贴问题截图后直接CtrlAltV粘贴它会自动把图片保存到指定目录并插入 Markdown 图片语法。默认配置是保存到当前文件所在目录我在设置里把它改成了${currentFileDir}/assets图片统一管理路径整洁很多。2.3 Obsidian 基础配置仓库结构、附件路径、核心插件Obsidian 的安装同样简单重点在于创建“仓库”Vault时想清楚文件夹结构。我通常建议用这样的结构笔记仓库/ ├── 00 Inbox/ # 临时收集的碎片内容 ├── 10 Projects/ # 按项目分类的文档 ├── 20 Areas/ # 长期维护的领域知识 ├── 30 Resources/ # 参考资料、摘录 ├── 90 Archive/ # 归档内容 └── assets/ # 所有附件图片、PDF等这个结构借鉴了 PARA 方法好处是内容有了明确的归属找东西不需要靠搜索。设置里需要开启“默认新附件位置”为assets文件夹这样粘贴进来的图片都会自动归拢。Obsidian 的核心插件里“大纲”和“标签面板”建议默认开启前者就是 Markdown 的标题结构对应文档目录后者方便按标签筛选内容。社区插件里我强烈推荐 Dataview它可以把笔记里的元数据比如创建日期、标签、状态自动生成表格实现类似数据库查询的效果不过这是进阶玩法刚开始用不上。3. Markdown 核心语法与高频细节3.1 基础语法速查标题、列表、引用、代码块Markdown 的基础语法网上一搜一大堆这里不把完整的语法文档抄一遍只挑高频且容易用错的来讲。标题用#到######表示六级注意#后面一定要跟一个空格否则有些渲染器不识别。列表分无序列表-或*和有序列表1.嵌套列表需要缩进两个空格或一个 Tab。引用用可以嵌套比如就是引用的引用。代码块用三个反引号包裹可以在后面标注语言类型实现语法高亮def hello(): print(Markdown code block)行内代码用单个反引号比如pip install typora。链接语法是[显示文本](URL)图片语法是区别只在一个感叹号。这些基础语法看起来简单但组合起来可以完成 90% 以上的文档写作需求。真正容易出错的反而是细节比如中英文标点混用、空格缺失、列表和段落之间的空行这些会导致渲染结果和预期不符。3.2 换行与段落的正确姿势两个空格还是空一行换行是 Markdown 新手的第一个坑。在 Markdown 里直接按一下回车换行在渲染结果中是不生效的就是说句子虽然换行了但显示出来还是连在一起的。想要真正的换行有两种做法。一是在行尾加两个空格再按回车这是 Markdown 标准语法但肉眼看不到空格经常忘记加。二是在两行文字之间空一行这样会生成一个新的段落段间距更大视觉上也更清晰。我自己的习惯是优先用空一行的方式因为两个空格在编辑时看不见回头维护的时候容易懵。Typora 有个特殊处理直接回车也能换行这是它为了所见即所得做的优化。但如果你把同一份文件放到 GitHub 或者其他编辑器里换行可能就不生效了。所以写文件时最好还是按照标准语法来不要依赖特定编辑器的“温柔”处理。3.3 表格对齐方式、复制粘贴、转换 Excel表格是 Markdown 里写起来最费劲、但又是最常用的语法。基础格式是这样的| 列1 | 列2 | 列3 | | ---- | ---- | ---- | | 内容 | 内容 | 内容 |表格的对齐方式通过第二行分隔行的冒号来控制---左对齐:---:居中---:右对齐。比如| 左对齐 | 居中 | 右对齐 | | :--- | :---: | ---: | | 1 | 2 | 3 |实际使用中我发现手写表格效率太低特别是数据多的时候。我自己的做法是如果表格数据在 Excel 里直接用在线工具把 Excel 转成 Markdown 表格或者用 VS Code 的插件格式化而不是手工一列一列敲。反过来如果想把 Markdown 表格复制到 Excel 里可以在渲染后的网页视图里选中表格直接复制粘贴到 Excel 就是规规矩矩的表格。Typora 里选中表格后右键也有 “复制为 CSV” 的选项这个配合 Excel 也很好用。3.4 图片路径与图片管理相对路径、图床、批量处理图片问题是 Markdown 工作流里最容易被忽视、后患无穷的环节。你本地写了一篇文章图片用的绝对路径比如C:\Users\me\Pictures\1.png发到博客平台上别人根本看不到。正确的做法是使用相对路径。推荐的文件组织方式是这样的docs/ ├── 文章.md └── assets/ └── 文章/ └── 1.png在文章里引用图片的路径就是assets/文章/1.png。这样整个文件夹传到 GitHub、复制给同事、放进 Obsidian 仓库图片都不会丢。Typora 和 VS Code 的 Paste Image 插件都可以配置成自动存到这个路径。还有一个思路是使用图床把图片传到云端比如 GitHub 仓库、对象存储然后在文档里引用云端 URL。好处是文档体积小、分享方便坏处是依赖网络、图床可能失效。对个人知识库来说我建议本地相对路径为主图床只用于博客文章的发布场景。3.5 特殊符号与扩展语法圈 1 到圈 19、方框、高亮、脚注中文写作里经常要打圈号数字比如①到⑲。在 Markdown 里直接输入这些符号倒是可以但有时候你会发现在某些字体下显示不出来或者复制到别的地方乱码。我的做法是用 Unicode 码直接输入① 是\u2460⑲ 是\u2472输入法里一般也直接能找到。如果要在 Markdown 里做出“方框”效果也就是任务列表语法是这样的- [ ] 待办事项 - [x] 已完成事项注意-和[ ]之间要有空格渲染后会显示为可勾选的复选框。在 GitHub 和 Obsidian 里都可以直接点击勾选做任务管理很方便。扩展语法方面Typora 支持的高亮用文字脚注用[^1]然后在文末定义[^1]: 脚注内容上标用^文字^下标用~文字~。这些语法在标准 Markdown 里不支持所以写文件时要想清楚目标渲染环境是否兼容别写完了换一个平台全乱掉。4. 进阶功能与工具链集成4.1 Mermaid 图表流程图、时序图、甘特图的 Markdown 实现Mermaid 是一个用文本描述图表的工具最大的价值是让 Markdown 文档里也能直接写流程图、时序图、甘特图。我最初接触它是为了在 GitHub README 里画架构图后来发现写技术方案、API 文档也特别有用。Mermaid 的基础用法是在代码块中标注mermaid语言然后写图表定义。比如一个简单的流程图graph TD A[开始] -- B{判断} B --|是| C[执行] B --|否| D[跳过]这里有三个核心概念要注意。第一是节点定义A[文本]表示方块节点A(文本)表示圆角节点A{文本}表示菱形判断节点。第二是连线方式--是带箭头实线---是不带箭头实线-.-是带箭头虚线是带箭头粗线。第三是子图用subgraph关键字可以把相关节点圈起来这在画复杂架构图时特别实用。VS Code 的 Markdown Preview Enhanced 和 Typora 都内置了对 Mermaid 的支持写完后在预览窗口直接可以看到渲染结果。GitHub 和 GitLab 也支持在 Markdown 文档里渲染 Mermaid 图表所以用它写技术文档完全没有兼容性问题。这份教程里就不画完整图表了结构上有需要时Mermaid 是首选方案。4.2 自动生成目录VS Code 插件与 Jupyter Notebook 场景Markdown 文档长了以后没有目录找内容确实费劲。在 VS Code 里Markdown All in One 插件提供了生成目录的快捷方式打开命令面板CtrlShiftP输入 “Create Table of Contents”它会自动扫描文档里的所有标题在光标处插入目录列表。这种目录是带锚点链接的点击就能跳转发布到 GitHub 上也能用。Jupyter Notebook 本身是用 Markdown 写文本说明的但目录支持比较弱。好在有专门的扩展解决这个问题安装 jupyter-contrib-nbextensions然后启用 Table of Contents 插件Notebook 左侧就会多出目录导航。这个方法在数据分析和机器学习项目里很实用代码多、章节多的时候有目录才能快速定位。Obsidian 不需要额外插件右上角的“大纲”面板天然就是目录而且支持实时折叠。写长文时我习惯把大纲面板打开配合标题拖动调整结构。4.3 Markdown 转 WordPandoc 工作流与 Coze 自动化把 Markdown 转成 Word 是很多人在实际工作中绕不开的需求特别是团队协作里对方只用 Word 的情况。标准解法是安装 Pandoc然后执行pandoc input.md -o output.docx这个命令会生成一个最基础的 Word 文档但样式很简陋。优化的做法是准备一个自定义的 Word 参考模板先用 Word 制作好标题字体、正文字号等样式然后导出为reference.docx之后每次转换都加上--reference-docreference.docx参数pandoc input.md -o output.docx --reference-docmy-style.docx这样生成的 Word 文档在样式上基本符合需求后续只需要微调个别格式。如果你用的是 Coze 这类自动化工作流平台可以把“Markdown 转 Word”也接进去本质逻辑是一样的先解析 Markdown 内容再调用转换工具输出 Word最后把文件发给用户。但要注意的是在线自动化工具处理复杂表格和图片路径时容易出问题最稳妥的方案还是本地安装 Pandoc。4.4 浏览器一键抓取MarkDownload 插件与 WordPress 发布有时候你在网页上看到一篇好文章想存成 Markdown 笔记手动复制粘贴再整理格式效率很低。这个场景可以用浏览器插件解决我常用的是 MarkDownload它是开源的 Markdown Web Clipper 插件支持 Chrome 和 Firefox。安装后在任意网页上点击插件图标它会自动分析网页结构把正文内容提取出来并转化成 Markdown 格式。默认配置下会保留标题、链接、图片、代码块等结构。这里有个小技巧在插件设置里开启“自动下载”配合 Obsidian 的assets文件夹可以把网页直接存进本地仓库省去手动整理的步骤。如果你用 WordPress 写博客又习惯用 Markdown 写初稿有几个方案可以实现转换。最简单的做法是安装 WordPress 的 Markdown 插件比如 Jetpack 内置的 Markdown 模块启用后可以在编辑框里直接写 Markdown发布时自动转为 HTML。另一个方案是把 Markdown 文件用 Pandoc 转成 HTML 后再粘贴到 WordPress 的文本编辑器里。前者适合日常更新后者适合批量导入。5. 常见问题与排查技巧5.1 表格在 GitHub 上显示错乱GitHub 对 Markdown 表格的语法要求比本地编辑器更严格。最容易出的问题是表格前后没有空行、表头分隔行的---数量不够、单元格里有竖线|被误解析。排查方法是检查表格前后是否各有一个空行比如上面是段落 | 列1 | 列2 | | --- | --- | | 数据 | 数据 | 下面是段落如果单元格内容本身包含|符号需要用反斜杠转义| 转义示例 | 内容 | | -------- | -------- | | 管道符 | a \| b |用 Markdown All in One 的表格格式化功能快捷键ShiftAltF可以自动修复表头对齐问题。5.2 图片路径失效显示为破损图标图片失效的原因绝大多数是路径写错了或者图片文件没有放到正确位置。排查时先确认图片文件是否真的存在于你写的路径下然后确认路径大小写是否和文件名一致最后确认用的是相对路径还是绝对路径。一个很隐蔽的问题是不同系统对路径分隔符的处理不一样。Windows 用反斜杠\但 Markdown 里反斜杠是转义字符图片路径里的\常常会被吃掉。所以 Markdown 图片路径统一应该用正斜杠/比如assets/文章/1.png即便在 Windows 下也能正常解析。另外如果发现图片在本地正常但推到 GitHub 上失效多半是 GitHub 对图片路径大小写敏感而本地文件系统不敏感。文件名是Cat.png路径写成cat.png本地能显示GitHub 上就挂了。解决方法是文件名全部用小写路径中的目录名也统一小写。5.3 VS Code 插件不生效或预览空白VS Code Markdown 插件不生效首先检查插件是否真的安装了。打开扩展面板搜索插件名确认状态是“已启用”。如果插件已安装但快捷键无效检查是否和其他插件冲突可以在键盘快捷键设置里搜命令名手动指定一个新的键位。预览空白的问题通常是预览引擎出了问题。Markdown Preview Enhanced 偶尔会缓存异常解决办法是执行CtrlShiftP输入 “Markdown Preview Enhanced: Reload Preview” 或者直接重开窗口。另一个可能是防火墙或代理设置阻止了预览引擎加载资源检查一下终端里有没有报错信息。5.4 Jupyter Notebook 无法生成目录Jupyter 的目录插件是 nbextensions如果安装了还是看不到目录按钮多半是没启用。运行jupyter nbextension enable toc2/main也可以打开 Jupyter 主页面进入 Nbextensions 标签手动勾选 Table of Contents 2。还有一类情况是JupyterLab 和经典 Notebook 的插件机制不互通在 JupyterLab 里需要安装jupyterlab/toc扩展。我遇到过用户明明用的是 JupyterLab却按经典 Notebook 的方法装插件自然没有效果。先确认你打开的是 Lab 还是经典界面。5.5 换行不生效与中英文标点混用问题换行问题在前面提过这里再补充一个典型场景在列表项内换行很多人的处理是按下回车后继续写结果渲染出来列表项被拆成了两个。- 列表项第一行 继续写的内容前面加两个空格缩进这个“继续写的内容”会作为同一个列表项的新段落显示。如果你不想缩进太多也可以使用br标签手动插入换行- 列表项第一行br 这一行紧跟在第一行下面中英文标点混用的问题更隐蔽。全角冒号和半角冒号:在 Markdown 语法里意义完全不同比如[链接文本](URL)中如果用了全角括号或冒号整个链接语法就失效了。我个人的排查经验是凡是语法不生效先检查标点符号是不是全角状态输入的。养成写 Markdown 时切换到半角标点的习惯能少踩一半的坑。6. 完整实操从零搭一套个人 Markdown 写作环境6.1 场景设定与目标假设现在你从零开始想搭建一套完整的 Markdown 写作环境需求是三端协同Windows 办公机为主力写作手机端用 Obsidian 随时记录写完后一键导出为 Word 发给同事同时能把内容同步到 GitHub Pages 作为个人博客。这套环境涉及的工具包括Typora写作主力、VS Code代码和进阶编辑、Obsidian移动端同步和知识管理、Pandoc格式转换、Git版本管理和博客发布。听起来多但实际装起来半小时内能搞定。6.2 逐步搭建流程第一步安装 Typora。官网下载 Windows 版本默认配置即可。打开偏好设置在“通用”里把图片保存路径设为./assets勾选“优先使用相对路径”。第二步安装 VS Code 和四个插件Markdown All in One、Markdown Preview Enhanced、Paste Image、Prettier。打开设置搜索pasteImage.path设为${currentFileDir}/assets。第三步安装 Git。官网下载安装包一路下一步。配置用户名和邮箱git config --global user.name yourname git config --global user.email youremailexample.com第四步安装 Pandoc。下载安装后打开终端验证pandoc --version第五步在 D 盘创建目录结构并初始化 Git 仓库mkdir -p D:/Notes/assets cd D:/Notes git init第六步手机安装 Obsidian创建仓库时选择“打开本地仓库”定位到 D 盘 Notes 目录。如果需要远程同步可以把 Notes 文件夹放到 OneDrive 或坚果云网盘里手机上同步后打开就能看到同样的内容。第七步测试完整流程。新建一个测试文档粘贴一张截图验证图片自动保存到 assets 目录。然后执行 Pandoc 转换 Word验证导出功能正常。6.3 最终效果验证完成以上步骤后写文档的流程应该是这样的打开 Typora新建文档开始写作。截图后CtrlAltV直接粘贴图片图片自动存到assets/。写完后用 Markdown All in One 生成目录如果是 VS Code 编辑。需要发 Word 时在 Typora 里文件 → 导出 → Word会自动调用 Pandoc。需要同步到手机时由于已经把 Notes 文件夹放到网盘目录Obsidian 会自动同步。需要发布到博客时用 Git 把 Notes 仓库推到 GitHub配合 Pages 服务自动渲染。这个流程的核心优势是所有内容都是纯文本 Markdown没有私有格式任何时候想换工具都可以无缝迁移。数据备份也简单把整个 Notes 目录压缩或者推到远端仓库就行。7. 写在最后的经验排版工具和技术选型说到底是服务于“更高效地写作”这件事。Markdown 的最大价值不是让你排版多漂亮而是让你能专注于内容本身在完全不思考格式的情况下产出结构清晰的文档。我踩过不少坑最有价值的一条经验是从一开始就建立规范比后期整理省力一百倍。图片统一放 assets、文件名统一小写、表格前后留空行、换行用空段落这些规范在最初会有点麻烦但坚持一个月后你会发现自己写文档的速度明显快过用 Word 的时候。还有一个建议是不要过度追求工具。我见过很多人花大量时间折腾 Obsidian 插件、自建博客主题、配置自动化工作流结果真正花在写作上的时间少得可怜。工具链够用就好Markdown 的核心语法半小时就能学会剩下的时间应该用来写内容本身。如果后续想继续扩展可以考虑的方向包括用 GitHub Actions 自动构建个人博客、把 Markdown 工作流接入思源笔记或 Notion、给 Pandoc 配置一套自己的 LaTeX 导出模板。每一个方向都有足够深的玩法但前提是一份干净、规范、不受工具绑定的 Markdown 内容库。基础打好了后续怎么扩展都行。