写博客这件事我摸索了挺多年才彻底稳定下来。早期用过各种在线编辑器后来折腾过本地 Word再后来转到 Markdown 这套流程里就再也没回去过。Markdown 吸引我的核心点特别简单它让写作重新聚焦在“内容”上而不是“排版”上。你只需要记住几个符号就能完成标题、加粗、列表、引用、表格这些日常 90% 的排版需求剩下的交给渲染器去处理。这篇博文就把我实际用了几年 Markdown 写博客的经验、踩过的坑、摸出来的工作流一次性摊开讲清楚适合刚开始接触 Markdown 的写作新手也适合已经在用但想优化细节的进阶用户。1. 为什么我坚持用 Markdown 写博客1.1 内容与样式分离这是最底层的逻辑Markdown 最大的价值是让内容与样式彻底解耦。你在记事本里写一行# 标题它知道你表达的是“一级标题”你写**加粗**它知道这里是“强调”。但具体显示成大号黑体还是红色加粗完全由使用场景决定——同一个文件扔到 GitHub 上是代码库的 README扔到博客系统里是文章标题扔到公众号编辑器里又能变成带样式的排版稿。这种“一处写作、多处发布”的特性对内容创作者来说就是生产力。很多人误以为 Markdown 是程序员专用其实恰恰相反。排版越复杂的人越应该用 Markdown。因为它把“要不要加粗”“字号多大”这种低价值决策全部省掉让你把脑力花在真正重要的地方——段落结构是否清晰、论据是否充分、表达是否准确。我写一篇 3000 字的博客用 Markdown 状态下的实际排版耗时基本为 0因为所有格式都是边写边带出来的不需要回头再选中文字去点工具栏。1.2 纯文本的隐性优势永不损坏、随处可改、方便版本管理Markdown 文件本质是纯文本这一点带来的好处往往被低估。我最早写博客用的是在线富文本编辑器后来想迁移到别的平台复制粘贴过去格式全乱图片链接全失效那叫一个难受。换成 Markdown 之后每个文件就是一个.md后缀的纯文本记事本能打开手机能打开任何一台电脑都能打开哪怕十年后所有编辑器都停更了文件也依然可读可用。纯文本还有一个隐藏优势——方便走版本管理。我自己的博客仓库是用 Git 管理的每篇文章从初稿到定稿都有历史记录改错了可以随时回滚。这在富文本里几乎做不到富文本文档通常是一坨无法 diff 的内容一旦改动就彻底丢失原貌。而 Markdown 配合 Git每一处增删都能清楚地看到多轮改稿也不怕丢内容。1.3 Markdown 生态和博客系统的天然契合现在几乎所有主流博客平台、静态站点生成器、笔记软件、AI 工具都支持 Markdown。你用一个标准语法写出来的文档几乎可以在任何地方流通——Hugo、Hexo、VuePress 这类静态博客直接拿来当源文件WordPress、知乎、语雀支持 Markdown 粘贴Obsidian、Notion、印象笔记也全都有 Markdown 兼容模式。生态的通用性才是 Markdown 真正恐怖的地方这不是某一个软件的优势而是整个行业形成的共识标准。2. 基础语法没你想象中那么简单新手最容易踩的 5 个坑2.1 换行到底怎么换这个坑坑了无数新人Markdown 语法刚上手时最反直觉的是换行。你按一次回车在纯文本里看起来换了行但渲染出来通常不会真的换行而是变成一个空格继续跟后面的内容在同一行。这是因为 Markdown 的换行规则沿用了 HTML 的段落逻辑——只有出现空行才表示一个段落结束。解决办法有三种在两个段落之间留一个空行这是推荐做法语义最清晰在行尾加两个空格再回车会生成一个软换行适合诗歌或地址这类需要“打断但不断段”的场景直接使用 HTML 标签br最明确也最可控。我自己日常写作只用第一种在 Markdown 里“一个空行 分段”这个习惯养成后写出来结构天然清爽。第二种带空格换行其实很容易被误删尤其在手机上编辑的时候空格不易察觉删掉之后整段内容悄悄变成一行用户体验很差。所以我建议新手阶段干脆不用行尾空格严格走“空行分段”即可。2.2 对齐方式Markdown 原生不支持但有两个变通方案写过博客的人都知道偶尔会有居中对齐或右对齐的需求比如表格下方的注释、图片说明文字。但是 Markdown 原生语法里没有对齐标记这算是一个经典的“盲区”。网上搜“markdown 对齐方式”能看到一堆人问答案也很统一——用 HTML 标签。最简单的做法是使用 HTML 的div aligncenter或者p aligncenter包裹内容。我经常在图片注释和表格上方注明统计口径时用这个方式p aligncenter表1近三个月博客访问量统计/p此外如果目标平台需要也可以用center内容/center但这个标签在 HTML5 里已经被废弃我一般不推荐。最稳妥的还是在段落里套一个div aligncenter.../div或者干脆用 CSS 类只是后者在本地预览时可能不生效。注意这些标签在 GitHub、Typora、Obsidian 里都能正常渲染但个别平台出于安全考虑会过滤部分 HTML发布前最好看一眼效果。2.3 带圈数字①到⑲怎么打这个需求真有用户需要写技术文档、列步骤清单时偶尔会用到带圈数字像 ① ② ③ 一直到 ⑲。这个词条能上热搜就是因为确实有不少人在 Markdown 里琢磨过这事。严格来说带圈数字不是 Markdown 语法要管的事它属于 Unicode 字符输入问题跟写不写 Markdown 没有关系。我的经验是直接用输入法打“yi”看候选字或者用 Windows 的Win .打开符号面板去找。在 Markdown 里使用带圈数字有两种思路直接复制 Unicode 字符比如 ①U2460到 ⑲U2472放到正文里就行这是最简单的方式如果目标平台支持 HTML 实体可以用#9312;这样的 Unicode 码位表示不过多数场景不需要这么麻烦。需要提醒的是20 以上的带圈数字在常用字体里支持不完整很容易变成豆腐块我一般到 ⑲ 就改用括号数字。2.4 超链接和图片标签的语法几乎一样但有个关键差别超链接的语法是[文字](链接)图片的语法是差别就一个感叹号。因为结构相似新手容易记混也容易写出奇葩问题。比如有人会在图片标签里加一个鼠标悬浮提示写成这块 Typora 支持但是复制到某些平台会失效。所以我自己写博客时尽量只用最基础的双括号形态高级功能不依赖编辑器扩展。图片路径还有一个容易踩的坑如果图片文件放在本地某个临时目录写死一个绝对路径C:/Users/xxx/Desktop/blog/img/pic.png那么换电脑、换平台之后就全挂了。更合理的做法是把文章和图片放在同一个项目目录里用相对路径引用图片比如。这样整个文件夹拷到哪都能正常显示上传到博客平台时也方便统一处理。这个点后面在“图片路径”专门讲。2.5 表格语法看起来简单复制和转换时才头疼Markdown 表格写起来不复杂第一行是表头第二行是---分隔 剩下的行就是单元格内容。真正折磨人的是表格后面遇到换行、竖线、对齐方式这些细节。比如单元格里要显示|这个字符必须转义成\|想让某一列右对齐要在分隔行右侧加冒号比如|---:|。我见过一些同事写复杂表格时因为一列里塞了一长段文本整个表格在移动端挤压得没法看后来就改成用 HTMLtable处理“长内容表格”。表格相关的另一个高频需求是“复制到 Excel”和“转换成 Excel”。直接复制 Markdown 表格到 Excel默认会挤在一列里显得很难搞其实用 Excel 的“数据 → 分列”以竖线为分隔符切分一次就能得到规整的表格。不过更省心的方式是用现成工具转比如 Typora 复制表格时会自动带上间距对齐的管道符直接粘贴到 Excel 有时能触发自动分列如果不行就借助 Markdown 表格转 Excel 的在线工具后面“生产力工作流”一节我会专门讲。3. 编辑器选型和插件搭配这题没有唯一答案3.1 Typora 依然是最舒服的写作工具之一Typora 火了这么多年至今仍是我给新手推荐的首选。它最大的特点是“所见即所得”你输入#加空格之后马上能看到标题样式不用左右分屏预览整个界面干净得像一张纸。很多不喜欢 Markdown 的人就是因为用过 Typora 之后改观的——原来 Markdown 也可以像 Word 一样随手写。Typora 比较实用的配置项有几个图床设置、自动保存、导出配置。在“文件 → 偏好设置”里可以设置图片插入行为比如“复制图片到当前文件夹下的 images 目录”这能从根本上解决图片路径问题。再比如说导出 PDF / Word / HTMLTypora 内置了 Pandoc 支持Windows 版本单独安装一键导出非常方便。我建议拿到 Typora 第一件事就是设置“插入图片时自动上传到图床”或者“自动复制到相对路径”不然写带图文章时会很痛苦。有个小细节值得提一下Typora 的主题可以改我用的是一款比较护眼的浅青色主题长时间写稿比默认白色舒服很多。你如果审美要求高可以在 Typora 的 themes 目录里放自己喜欢的 CSS 主题。3.2 VS Code Markdown All in One程序员写博客的“终极形态”VS Code 对于写 Markdown 来说最大的优势是插件生态。最核心的插件叫 Markdown All in One它集成了自动格式化、目录生成、列表缩进、快捷键这些高频功能。安装之后常用快捷键包括Ctrl B加粗、Ctrl I斜体、Ctrl Shift ]提升标题级别。另一个经常让人犯迷糊的功能是“Markdown 预览”VS Code 默认预览快捷键是Ctrl Shift V侧边预览是Ctrl K V。折腾过的人应该懂这两个快捷键一旦没记住每次都得去菜单里找按钮非常影响体验。VS Code 里还有一个容易被忽略却强大的能力——Mermaid 图表支持。在.md文件里写 mermaid 代码块然后在预览面板里就能看到流程图、时序图、甘特图的渲染结果。我在技术博客里画架构图时经常用这个方式不用再单独打开画图工具一套 Markdown 就全部搞定。拿mermaid包裹绘图代码预览即可渲染这在分享技术方案时效率奇高。不过我也提醒一句Mermaid 语法很“吃”格式常见报错是缩进不对、节点命名不用英文、箭头语法老记错反正边写边看预览有错立刻就能发现。3.3 Obsidian 的知识管理玩法与折叠块Obsidian 是另一个我非常常用 Markdown 笔记工具。它的核心卖点是“双向链接”和“知识图谱”底层文件同样是.md所以不存在数据锁定问题。对于写博客的素材积累阶段Obsidian 很适合——先建一个“素材库”把平时看到的文章摘录、技术点、灵感随手记成 md再通过链接串起来等写正式博客时就能快速调用。Obsidian 里让我惊奇的功能之一是可以折叠 Markdown 块。默认情况下Obsidian 会识别标题层级并在一级标题左侧显示折叠箭头。如果你需要折叠任意段落也可以用details标签包起来这样阅读时默认只展开关键信息想看细节再点击展开。这个功能对长文博客很实用比如文章开头放“目录”中间放“代码”结尾放“附录”通过折叠块让首屏变得非常干净。3.4 网页剪藏利器markdownload如果你经常从网页收集素材、保存网页为 Markdown 格式markdownload 这个浏览器插件是不可错过的工具。它能在浏览器里一键把当前网页内容转换成干净的 Markdown并且能把图片一并保存到本地目录。相比某些阅读模式插件、浏览器自带“另存为”功能markdownload 生成的 Markdown 结构化更强标题层级、代码块、超链接都保留得很完整基本不用二次清理。我自己写技术博客时的习惯是看到一篇好文章用 markdownload 把它保存到 Obsidian 素材库先放两天“冷藏”写文章的时候再翻出来。长期积累下来的素材库比临时搜索高效得多——因为你能记住自己收藏过什么比记住零散 URL 强多了。3.5 图片路径的终极方案一个项目一个 images 目录图片路径问题是 Markdown 写作里最能“劝退”新手的一个细节。问题是多平台都相关本地写好了图传到博客平台图就裂了或者文章上传到 GitHub 之后图片找不到了。我的终极方案其实特别简单每篇文章的文件名做成一个目录文章和图片放在同一级目录的 images 子文件夹中博客源码全部放在同一个 Git 仓库。比如blog/ ├── posts/ │ ├── 2024-05-21-markdown-blog/ │ │ ├── index.md │ │ └── images/ │ │ ├── pic1.png │ │ └── pic2.png文章里引用图片就写。不管在本地 Typora、VS Code还是部署到 GitHub Pages、Vercel图都能正确显示。如果还要把文章投到公众号、知乎之类的内容平台就用 Typora 的“导出图片”或者直接用图床上传反正源码目录统一什么时候想再迁移都能一键搞定。4. 把 Markdown 变成真正的生产力工作流4.1 Markdown 转 Word写论文和正式文档的人必备技能总有人说“Markdown 只适合写博客正式文档还得用 Word”。以前我也这么觉得后来发现是工具没用对。Markdown 转 Word 的黄金工具是 Pandoc它是命令行程序一句命令就能把.md转成.docxpandoc input.md -o output.docx这背后的原理是 Pandoc 会把 Markdown 解析成文档语法树再套用 Word 的样式模板输出。默认生成的 Word 样式可能不够好看但你可以自定义一个 reference docx 模板把标题字体、正文字号、页边距都调成自己想要的之后每次生成的 Word 就都是统一风格了。这个“一次调模板永久复用”的思路我觉得是写正式文档最舒服的状态。Typora 里也内置了导出 Word 的按钮本质上是调用 Pandoc。如果没有安装 Pandoc它会提示你先安装。我自己日常更习惯用命令行直接操作因为可以批量处理一个文件夹里所有文章。比如for f in *.md; do pandoc $f -o ${f%.md}.docx; done这样一口气转换整个目录效率比手动逐个导出高得多。4.2 Markdown 表格转 Excel复制粘贴还是命令转换Markdown 表格转 Excel需求非常高频。开会时同事发来一个 Markdown 表格你需要整理成 Excel或者反过来需要把 Excel 数据粘贴成 Markdown 表格。两种方案实测都能走通方案一复制 Markdown 表格粘贴到 Excel选中“数据”里的“分列”用“|”作为分隔符。如果复制时带上了首尾的竖线分列时会多出空列手动删掉即可。方案二用 pandoc 转换pandoc table.md -o table.xlsx但要注意pandoc 默认生成的 xlsx 只有一个 Sheet 且格式简单对复杂合并单元格无能为力。如果只是简单数据表pandoc 完全够用如果是复杂报表我建议先把 Markdown 转成 CSV再用 Excel 打开pandoc table.md -t csv -o table.csvCSV 在 Excel 里打开后做二次加工灵活性高很多。4.3 Java 程序要做 Word 转 Markdown这件事并不简单看到热搜里有“java word 转 markdown”我得说这个需求场景相当明确——企业里有大量历史 Word 文档想统一转成 Markdown 进入内容管理系统或知识库。Java 生态里能解析 Word 的库是 Apache POI它可以读取.docx文件中的段落、表格、样式。但“满格式 Word 转 Markdown”是真的难因为 Word 里的样式过于丰富浮层、文本框、批注、复杂表格、嵌入对象全是 Markdown 不支持的。我的建议是别指望一步到位。先评估源文档的复杂度如果大多是常规标题、正文、列表、简单表格可以用 POI 开发一个转换工具一个段落对应一个 Markdown 块如果文档里充满复杂样式转出来的 Markdown 大概率要人工校对。一个务实的折中方案是先转 HTML再用 HTML 转 Markdown比如用jsoup解析 HTML然后用flexmark-java这种库直接把 HTML 转换成 Markdown AST。对整个转换链路的准确率会提升不少。这点要强调批量转换永远要做“抽检”在实际工作中踩过太多“90% 文档转得好好的剩 10% 栽在合并单元格或图片定位”的坑。4.4 在 AI 工作流平台里处理 Markdown 转 Word“dify markdown转word中序号自动编号”这个热搜词很有意思它点出了很多人在 Coze、Dify 这类 AI 工作流平台上做文档自动生成时的痛点。比如你用 AI 生成了 Markdown 格式的合同、周报然后想转成 Word 发给同事最头疼的就是“AI 写的 Markdown 里明明用 1. 2. 3. 编号了但转出的 Word 序号乱掉或者所有列表都变成普通文本”。这个问题的本质在于Markdown 里的有序列表编号在转换器里常常被当成纯文本而不是 Word 的自动编号列表。不同转换引擎处理列表的方式不一样。pandoc 转换时会保留有序列表的语义但某些在线转换/浏览器打印功能可能就丢掉了列表样式。解决办法是在 AI 工作流里明确让模型输出规范 Markdown 结构尤其是列表项之间不要有多余空行。因为空行过多Markdown 渲染器容易把“有序列表”识别成“段落段落”转换到 Word 自然就没有编号了。另外如果工作流用的是 Python 的python-docx从 Markdown 生成 Word建议先用markdown库把内容转成 HTML 结构再通过 HTML 模板渲染 Word这样序号问题会好处理很多。最终如果实在不行就生成 PDF 而不是 Word既保住了排版又免去改格式的烦恼。5. 常见问题速查Markdown 写博客遇到的坑我都给你列全了5.1 图片裂了八成是路径或图床问题图片不显示是 Markdown 写作里最高频的问题。排查顺序就两步第一步在编辑器里看是否显示如果编辑器里显示了拷贝到目标平台才裂那多半是相对路径在本机有效、在其他环境失效。第二步检查路径里有没有中文或空格很多系统在路径解析时对空格敏感遇到过不少因为路径里有中文文件夹导致图裂的案例。我的规范是所有图片名都用英文小写连字符图片目录统一images这样能在最大程度上避免兼容性问题。如果要长期发布到公网平台就要认真考虑图床了。本地图片再规范也不具备公网访问能力。图床的选择逻辑看稳定性和费用也可以把图片传到和博客同一个对象存储里走自己的域名。但每次提图床都要老生常谈一句图床挂了 博客里的历史图片全废。所以我偏好的方案始终是“源码仓库里留一份原图”图床只是线上访问的分发层。5.2 预览不更新或 Mermaid 图表不渲染VS Code 里预览不更新经常是插件缓存问题重启窗口CtrlShiftP→ Developer: Reload Window基本能解决。Mermaid 不渲染大概率是语法不合规。最容易出岔子的几处节点文本用特殊字符不带引号、箭头符号写错、缩进不统一。写了 mermaid 块之后建议立即预览否则积压一堆错误排查起来很耗时。Mermaid 的 JavaScript 库还在持续更新老版本的 VS Code Markdown Preview Mermaid Support 插件如果很久没更新遇到新语法也可能渲染不了。遇到这种情况先把插件升到最新再检查语法。5.3 表格在移动端显示乱成一团Markdown 标准表格在窄屏上确实容易“溢出”尤其当某个单元格内容特别长。如果博客读者大量来自手机就得学会“拆表格”。经验法则每一列内容不超过 20 个字不要让表格整行变成一个超长链接不要在表格里塞代码块。遇到必须展示长内容的结构就改用列表或 HTML 表格并加上横向滚动容器。注意GitHub、Stack Overflow 这类平台会自动给表格套上横向滚动但个人博客的 CSS 不一定处理了建议写个通用样式覆盖.markdown-body table。5.4 换行问题与列表编号的连带影响前面讲过换行规则这里补充一个和列表有关的连带坑在列表项里如果忘记留空行或者多留空行后续段落会被误判成新的列表项。比如1. 第一条 继续写的内容 2. 第二条渲染后第一项和第二项之间的“继续写的内容”有时会顶到上一个列表项内部有时被识别成第二项的编号“1”一旦看到序号从 1 重新开始基本就是这里出了问题。写列表时我习惯让每个列表项的后续段落进行缩进对齐保证列表语义连续。5.5 快捷键记不住怎么办常用 Markdown 操作就那么几个标题升降级、加粗、斜体、插入链接、插入图片、预览、任务列表。不要试图把所有快捷键都背下来先记住最顺手的三个就够了。我在 VS Code 里的常用组合是CtrlShiftV预览、CtrlB加粗、CtrlShiftK删除行。Typora 里则基本是鼠标点选菜单快捷键混合使用因为它的所见即所得模式下工具栏已经足够方便。如果连快捷键都懒得记可以直接在 VS Code 里找命令面板CtrlShiftP输入命令关键词比如输入 “markdown” 就能看到所有 Markdown 相关操作。这个习惯帮我节省了大量记忆成本。6. 用 Markdown 和 AI 协作提问方式直接影响输出质量热搜里有一个很有意思的问题对 DeepSeek 这类 AI 提问是使用自然语言还是 Markdown 更容易让 AI 明白指令我自己实测下来的结论是使用带 Markdown 结构的提示词效果明显更好尤其当问题涉及多步骤、多条件、多输出格式时。原因不神秘。AI 对结构化输入的理解能力天然更强。你把需求写成“标题 子要点 约束条件 输出格式”的 Markdown 结构就像给 AI 一张条理清晰的任务单。相比之下一大段自然语言里如果有嵌套条件和并列约束模型容易漏读或混淆优先级。以下是我实际用的一种提问格式# 任务 帮我写一篇主题为「Markdown 写博客」的引流文章 ## 要求 - 目标读者刚接触 Markdown 的技术博主 - 语气平实、直接带少量个人经验 - 字数1500字左右 ## 输出格式 - 先用一段 150 字摘要 - 然后按小标题分段输出 - 结尾加上 3 条实用建议 ## 约束 - 不要用过多华丽辞藻 - 避免空泛的总结这样提问模型能精准抓取“任务→要求→格式→约束”四个层次输出的结构和质量通常都好过一段全凭模型自由发挥的对话。而且这个习惯本身也是 Markdown 思维的体现——用结构化方式组织信息让表达更清晰只是这次对象变成了 AI。我建议所有想用 AI 辅助写作的人都试试这种提问法你很快会发现它比依赖“灵机一动”的提示词强得多。最后再分享一个小技巧我每次写博客时都会在 Markdown 源文件顶部放一个写作日期和关键词列表方便后续检索正文写完后用 VS Code 的目录生成功能自动生成 TOC发布前再用 Typora 打开预览一遍确认图片和表格都没有问题。这套流程几乎不用动脑子却能让每一篇文章都保持统一的高质量输出。Markdown 真正的魅力就在于此它不会替你把文章写好但能让你把注意力全部放在“写”这件事上。