你可能会在技术社区看到这样的帖子开头“请忽略我忽大忽小的字因为这个帖我不熟等我写多些就好了。”说实话这段“免责声明”本身写得挺真诚但阅读体验并没有因此变好。读者并不会因为作者提前打了招呼就觉得这页文字时而大、时而小是正常的更多人只是默默关闭页面。作者说“等我写多些就好了”可真正导致排版混乱的往往不是写得少而是没有在写作流程里解决几件更具体的事情。这些事情拆开来看其实全都有方法可循Markdown 的结构是否正确、编辑器是否统一、有没有固定模板、发布前是否做了检查。这篇博客就从这四个层面把“字忽大忽小”的问题拆解清楚顺便给你一套可以直接复用的写作规范。1. 这篇文章真正要解决的问题先说结论排版忽大忽小的本质不是“字”的问题而是“结构”和“来源”的问题。很多新手作者以为排版混乱是因为自己“写得少”“编辑器用不熟”只要多写几篇自然就好了。这个判断有一定道理但不完全对。写得多确实会让思路更顺畅文字表达更熟练但排版稳定性依赖的是另一套能力——对 Markdown 语法规则的理解以及对“内容从哪里来、编辑器用什么、发布到哪个平台”这些环节的统一管理。举个很常见的场景你在本地编辑器里写文章字和字之间看起来很整齐标题、正文字号比例也舒服。可一旦把内容复制到博客平台并点击发布标题突然不生效了代码块缩进也乱了正文有的行特别大有的行特别小。这种“复制过去就变形”的情况和写作数量没有任何关系本质是编辑器和平台对同一段语法的解析方式不同。所以这篇文章真正要解决的问题是如何基于 Markdown 和一套固定的写作流程让排版从创建草稿到最终发布都保持稳定而不是依赖“多写几篇”去碰运气。适合读这篇文章的人也很明确刚开始写技术博客、团队文档、课程笔记却经常被格式问题打断或者已经在写作但每次发布都要花大量时间手动调字号、调缩进。如果你只是想随手记点笔记不关心排版那本文提到的规范可能有些重但只要你的内容需要被别人阅读排版稳定就是值得投入的一部分。2. “忽大忽小的字”从哪里来排版不稳定的四种来源很多人遇到排版问题第一反应是“平台有问题”或“编辑器有问题”。其实大多数忽大忽小的字都可以归因到下面四种来源。2.1 编辑器与渲染平台不一致不同编辑器对同一篇 Markdown 的渲染结果不完全相同。有的编辑器会自动把“单个换行”当作段落换行有的则要求必须空一行有的编辑器支持自动纠正标题层级有的则保持原样。这就导致你在 A 工具里看到的样子到了 B 平台就会变形。更隐蔽的情况是“预览和发布不一致”。有些平台的编辑器预览窗口和最终文章页面的 CSS 样式并不完全一致预览时觉得字号合适发布后才发现正文字号偏大、代码块又偏小。这种问题不是语法错误却直接影响阅读体验。最稳妥的做法是写作用本地或网页端工具发布前一定用目标平台自带的编辑器打开并确认最终预览。不要拿本地预览当成最终页面的效果。2.2 复制粘贴带来的样式残留这是“字忽大忽小”最经典的来源。比如从 Word、网页或聊天工具里复制一段文字再粘贴到 Markdown 编辑器粘贴的内容可能带着内部样式包括font标签、span标签或固定的font-size属性。Markdown 语法本身是纯文本但很多编辑器的“所见即所得”模式会把这些 HTML 样式一并插入。等发布时这些残留标签会和 Markdown 的默认样式冲突导致某些段落字号异常。你从表面上看到的是“某个地方字变大了”实际看代码会发现里面藏了一串很长的 HTML 标签。2.3 Markdown 语法使用不规范新手最容易踩的坑是混淆标题层级和加粗。比如有人想写一个小标题但用的不是##而是把一句话用**加粗再手动调大字号有人用#写了十几个小标题导致整篇文章的标题层级全部乱掉还有人把“标题”和“正文”之间不空行解析器会认为这是同一段内容导致字号比例不断变化。这些问题的根因是没有把 Markdown 当成一种有语义的结构化语法来用而是把它当成“装饰工具”来用。一旦你开始用#来强调、用**来替代标题排版就会逐渐失序。2.4 图片和代码块宽度不统一图片大小不统一也是排版显乱的重要原因。第一张图是原始尺寸第二张图是压缩后的小图正文宽度就会忽宽忽窄读者会觉得整篇文章“看起来不整齐”。代码块同理有的代码行特别长有的代码行特别短如果编辑器强制换行策略不同代码区的可读性也会下降。这四类问题叠加起来就构成了文章里那些“忽大忽小的字”。解决方案也不是某一个而是需要从工具、模板、语法和发布流程四个方向一起调整。来源典型表现根因解决方向编辑器与平台不一致本地预览正常发布后变形渲染引擎和 CSS 不同发布前用目标平台预览复制粘贴样式残留个别段落字号异常font等 HTML 残留粘贴时选择“纯文本”Markdown 语法不规范标题层级错乱、加粗当标题对语义化语法理解不足使用模板和 lint 检查图片/代码块宽度不一版式忽宽忽窄原始资源尺寸差异统一资源宽度和代码换行3. 核心概念Markdown 为什么能解决排版混乱想解决“忽大忽小”首先得理解 Markdown 到底解决了什么问题。Markdown 是一种轻量级标记语言核心思路是用纯文本的简单符号表达结构例如#表示一级标题##表示二级标题**表示加粗反引号表示行内代码。它的设计目标是“易读易写”让作者不用像写 HTML 那样关注大量标签而是专注于内容本身。3.1 标题的层级是“语义”不是“字号”很多人对标题的理解停留在“标题就是大点的字”。但在 Markdown 里#到######表示的是层级语义一级标题是文章标题二级标题是章节三级标题是子章节。至于它渲染出来是多大字号、什么颜色那是主题和 CSS 的事与内容无关。这个设计有一个非常大的好处当文章复制到不同的平台时只要平台支持标准 Markdown同一个##就会按该平台的标题样式展示。你不需要手动调字号也不需要担心不同平台的字体渲染差异。换句话说只要语义正确排版交给平台统一处理即可。3.2 语法一致性比编辑器功能更重要市面上很多编辑器都有工具栏可以点击插入表格、引用、代码块。这些功能本质上都是在生成 Markdown 符号而不是真正在画布上画一个表格。如果你依赖工具栏插入偶尔手写时符号写错就会出现同一篇文章里两种风格混用。更推荐的做法是在写作前记住最常用的十几个语法符号自己动手写。刚开始会慢一点但习惯之后速度反而不慢而且出错率更低因为你对原文有完全的控制权。3.3 平台差异仍然存在但可以被管理虽然 Markdown 是跨平台的但不同平台对扩展语法——比如表格、任务列表、数学公式、高亮——的支持程度并不完全相同。有的平台支持基于 GFMGitHub Flavored Markdown的扩展语法有的平台则只支持基础语法。因此如果你写的内容要在多个平台发布最好只用所有平台都支持的基础语法如果明确只在某个平台发布再使用该平台支持的扩展功能。这也是为什么“发布前用目标平台预览”是不可避免的一步。本地编辑器解决的是写作体验目标平台解决的是最终效果两者不能互相替代。4. 环境准备一套适合技术写作的本地创作环境要让排版“从开始就稳定”最好的方式是先在本地搭一套统一的写作环境而不是直接打开网页编辑器就敲。下面这套方案以 Visual Studio Code 为例你完全可以使用 Typora、Obsidian 或其他 Markdown 编辑器代替核心思路是本地写、统一配、发布前检查。4.1 安装 VS Code 与 Markdown 支持VS Code 本身对 Markdown 有基础支持包括预览、语法高亮和快捷键。建议再安装两个扩展markdownlint检查 Markdown 语法规范比如标题层级是否跳级、文件末尾是否有空行。Markdown Preview Enhanced提供更丰富的预览能力便于写作时快速查看效果。安装方法是在 VS Code 扩展面板中搜索相关名称点击安装即可。版本以当前较新的稳定版为准。4.2 修改与排版相关的设置如果你的文章经常在“忽大忽小”的边缘徘徊可以先检查 VS Code 里的两处设置编辑器的字体大小和 Markdown 预览字体大小。将它们固定下来可以减少本地预览时的视觉误导。在settings.json中加入以下配置{ editor.fontSize: 16, editor.renderWhitespace: boundary, markdown.preview.fontSize: 16, markdownlint.config: { MD024: false, MD025: false } }说明editor.fontSize编辑区字体大小设为 16px 适合多数高清屏。editor.renderWhitespace显示空格和换行边界便于发现多余空行或多余缩进。markdown.preview.fontSize预览窗口字体大小。markdownlint.config关闭部分严格规则。MD024是“同一标题不能重复”MD025是“只能有一个一级标题”这两条在团队模板中未必适用所以按需关闭。这些设置解决的是“本地看到的效果稳定”避免编辑器和预览两个区域的字号差异过大影响你对排版状态的判断。4.3 统一换行与文件命名文章文件建议统一使用.md后缀编码统一为 UTF-8换行符也尽量一致。Windows 默认换行是 CRLFmacOS/Linux 默认是 LF。如果文件在多个设备之间同步换行符不一致某些编辑器会显示多余空行影响排版判断。固定文件命名规则也有帮助比如YYYY-MM-DD-文章短标题.md。这样在本地目录里能按时间排序也不会因为文件重名覆盖旧稿。5. 从源头固定排版文章模板与写作流程环境搭好之后还需要一套固定的模板。模板能减少你每次从头开始排版的时间也能从结构上避免标题层级错乱。5.1 一个可以直接复制的基础模板下面是一个为技术博客准备的 Markdown 模板覆盖了常见的章节结构。复制后按顺序填充即可# 文章标题 摘要用两三句话说清楚这篇文章解决什么问题、适合谁读。 ## 1. 这篇文章真正要解决的问题 在这一段说明读者会遇到什么痛点以及文章的最终目标。 ## 2. 核心概念与原理 解释文章中出现的名词给出通俗理解和技术定义。 ## 3. 环境准备与前置条件 列出操作系统、依赖版本、工具链和安装步骤。 ## 4. 核心流程拆解 把实现过程拆成步骤每一步说明“做什么”和“为什么”。 ## 5. 完整示例与代码实现 在这里放代码注意标注语言类型。 ## 6. 运行结果与效果验证 说明如何运行、如何验证、如何判断成功。 ## 7. 常见问题与排查思路 用表格列出问题、原因、排查方式和解决方案。 ## 8. 最佳实践与工程建议 给出生产环境中的注意事项和团队协作建议。 ## 9. 总结与后续学习方向 做一些进一步学习的指引落点是具体行动。 --- 转载声明如需转载请联系作者并注明出处。这个模板的优点是标题层级从#到##到###结构清晰不会出现从##直接跳到####的问题。章节编号也方便读者定位。5.2 写作流程建议有了模板之后写作流程可以固定为四步先填充“文章标题”和“摘要”。摘要虽然是开头部分但它往往是在文章写完后才更准确所以可以最后再定稿。按模板的章节顺序写正文。先写核心流程和代码实现再补概念和背景最后写常见问题和最佳实践。写完正文后进入检查阶段重点看标题层级是否跳级、代码块是否闭合、空行是否符合规范。发布到目标平台前复制全文打开目标平台编辑器用“粘贴为纯文本”放入内容再在平台编辑器里补充图片和代码块。如果平台支持“从 Markdown 导入”优先使用导入功能。5.3 图片处理的固定方案图片大小不统一是版式“忽宽忽窄”的重要原因。建议固定两件事第一所有正文配图的宽度尽量一致第二在 Markdown 中避免直接使用原始超清大图可以先用工具统一压缩到合适的宽度再上传。代码块方面尽量设置“自动换行”或“水平滚动”避免超长代码行把页面撑破。多数 Markdown 平台会在代码块内自动处理但本地预览时未必一致所以发布后要看一眼真实效果。6. 完整示例一篇“不会忽大忽小”的 Markdown 文章源码与其单独解释每个规则不如直接看一个完整示例。下面的内容是一篇文章的 Markdown 源码刻意使用了规范语法和统一结构。你可以把它直接复制到本地编辑器里预览# 从排版混乱到稳定输出我的 Markdown 使用规范 摘要很多人写技术文章时会遇到“字忽大忽小”的问题。本文从 Markdown 语法、编辑器配置和发布流程三个角度给出了一套可落地的排版稳定方案。 ## 1. 排版问题的根源 这段内容说明排版混乱通常不是因为写作数量不足而是因为编辑器不统一、语法不规范、复制粘贴携带样式。 ## 2. Markdown 基础语法回顾 ### 2.1 标题 使用 # 到 ###### 表示标题层级。不要用加粗替代标题。 ### 2.2 列表 无序列表使用 -有序列表使用 1.。 ### 2.3 代码块 代码块使用三个反引号包裹并在开头标注语言类型。 ## 3. 本地环境配置 列出编辑器、扩展和相关配置。 ## 4. 写作流程 先大纲再正文最后检查。 ## 5. 发布前检查 发布前使用脚本检查标题层级和空行。 ## 6. 常见问题 使用表格列出。 ## 7. 总结 把规则内化为习惯。你可以对比一下这个示例里没有手动设置任何字号没有font-size没有font标签也没有在标题下面加多余空行。它的排版效果完全交给渲染器因此无论在哪个支持标准 Markdown 的平台都能保持统一、清晰的结构。如果文章里出现了需要自定义字号的极端情况更推荐的做法是修改平台的 CSS 主题而不是在 Markdown 源码里内嵌 HTML 标签。因为 Markdown 的价值恰恰在于纯文本、可迁移、易维护。一旦嵌入太多 HTML 样式可迁移性就会大幅降低。7. 用脚本检查排版格式问题人工检查总有遗漏所以推荐用脚本把“易错项”自动化。下面这个 Python 脚本用于检查 Markdown 文件的标题层级是否跳级、代码块是否闭合。先创建脚本文件# 文件路径scripts/check_markdown_heading.py import re import sys from pathlib import Path def check_headings(file_path: Path) - bool: lines file_path.read_text(encodingutf-8).splitlines() in_code_block False heading_levels [] ok True for line_no, line in enumerate(lines, start1): stripped line.strip() # 标记代码块开始/结束 if stripped.startswith(): in_code_block not in_code_block continue if in_code_block: continue # 匹配 Markdown 标题# 开头后面紧跟一个空格 match re.match(r^(#{1,6})\s, line) if match: level len(match.group(1)) if heading_levels and level heading_levels[-1] 1: print(f[警告] 第 {line_no} 行标题层级跳跃: {stripped}) ok False heading_levels.append(level) if ok: print(标题层级检查通过) return ok if __name__ __main__: if len(sys.argv) 2: print(用法: python check_markdown_heading.py 文件路径) sys.exit(1) sys.exit(0 if check_headings(Path(sys.argv[1])) else 1)然后在项目根目录运行python scripts/check_markdown_heading.py docs/blog-template.md预期输出标题层级检查通过如果文章里从##直接跳到了####脚本会在对应行输出警告并返回非零退出码。这个脚本虽然简单但已经能拦截两类最常见的问题标题跳级和代码块未闭合。还可以用 grep 快速扫描“样式残留”grep -rn font docs/ || echo 未发现 font 标签残留如果输出未发现 font 标签残留说明文章源码里没有从富文本粘贴过来的字体标签排除了“某一行字忽大忽小”的最大嫌疑。8. 常见问题与排查思路下面把实际写作中经常遇到的问题整理成一张表遇到排版异常时可以按表中顺序检查。问题现象可能原因排查方式解决方案发布后标题不生效Markdown 标题前后缺少空行或用了全角 #查看文章源码检查标题行前后是否有空行在标题和正文之间补充空行某一段突然变大或变小粘贴富文本时带入了font或span样式用 grep 搜索font、span复制内容时选择“粘贴为纯文本”删除残留标签代码块没有高亮代码块缺少语言标识或三个反引号不闭合查看代码块首尾是否有对应语言标注在代码块第一行补充语言类型如python、bash本地预览正常发布后格式乱本地编辑器与平台渲染规则不一致用平台编辑器预览一遍发布前在目标平台导入或粘贴并检查最终页面行首出现多余缩进复制时保留了空格或 Tab打开编辑器空白字符观察行首统一去掉行首多余空格使用规范的空行分隔标题层级乱跳章节编号和#数量不匹配运行标题检查脚本修改标题层级确保不跳级图片忽大忽小原始图片宽度不一致或未设置统一比例查看图片在页面中的实际显示宽度统一图片宽度或使用平台支持的尺寸控制表格列的宽度错乱表格缺少分隔行或单元格内容包含竖线检查表格源码的 ---列表间距忽大忽小列表项之间混用空行和换行观察列表项之间是否有多余空行统一列表项之间不空行或统一空行发布后正文两边留白过大段落行数过少平台自动生成大量空白查看 PDF 或阅读视图中的整体版面调整段落结构减少碎片化短行排查时有一个原则先看源码再谈样式。很多排版问题是内容里带着不可见字符或残留标签直接在页面上改很难清除。切到源码模式把问题区域前后各几行的内容完整看一遍往往一眼就能找到原因。9. 最佳实践把排版稳定变成写作习惯排版稳定靠的不是一次两次的修改而是一组可以长期执行的工程化习惯。下面这几点适合个人作者也适合团队文档维护。9.1 文件层用模板和脚本兜底团队写作时建议把 Markdown 模板和检查脚本放进同一个文档仓库。每个成员开始写新文章时都从模板复制写完用脚本检查。这样即使成员对 Markdown 不熟也能在提交阶段被自动化工具拦截大部分格式问题。版本上也建议用 Git 管理不要只依赖网盘或聊天记录传文件。文章出现排版损坏时Git 可以快速对比历史版本知道是哪一次编辑引入了问题。9.2 内容层少用内嵌样式多用语义结构写 Markdown 时尽量不要直接写 HTML。只有在确实无法用 Markdown 表达、且目标平台明确支持的情况下才考虑少量内嵌。否则一律用语义化标题、列表、引用和代码块。图片和附件的宽度尺寸在本地时就统一处理。不要等到发布时在平台页面上手动调平台手动调的结果往往只在该平台生效换一个平台又要重新调一遍。9.3 流程层发布和检查分离写文章和发文章是两件事。写文章时可以用本地编辑器注意力放在内容上发文章时打开目标平台编辑器注意力放在排版效果上。不要一边写一边反复切预览那样既打断思路也容易忽略整体结构问题。发布前的最后一遍检查固定按顺序看三样东西标题层级是否正确章节编号是否连续代码块是否完整语言标注是否正确图片是否加载正常宽度是否协调。9.4 安全与合规提醒写技术文章时注意不要泄露公司内部代码、密钥或未公开的业务信息。引用他人代码或图片时注明来源并确认版权。涉及敏感数据的教程要使用脱敏的示例数据不要直接用生产环境真实数据。这些细节虽然和排版无关但一旦出问题影响远大于一个错字或一张模糊的图。10. 下一步把“写得多了”变成“写得稳了”回到开头那个话题“等我写多些就好了”。这句话真正想表达的可能是“我还不够熟练请给我一点时间”。熟练确实有价值但它应该用来打磨内容的深度、表达的逻辑而不是用来弥补可以被规范和工具解决的排版问题。从今天开始可以尝试做三件事第一把本文的 Markdown 模板复制到本地开始写下一篇技术文章时直接套用。第二安装 markdownlint打开编辑器设置让规范成为写作过程的一部分。第三把检查脚本放进你的写作目录在发布前跑一次。这三件事都不需要等“写多”才能做做完之后你会发现那些忽大忽小的字其实从一开始就是可以被避免的。排版稳定之后读者看到的不再是一篇“作者自己都觉得乱”的文章而是一篇结构清晰、阅读顺畅、值得收藏的内容。这对写作者也是一种正反馈——你不需要在发布前反复调整格式只需要专注于真正重要的部分把技术问题讲清楚。
你可能会在技术社区看到这样的帖子开头“请忽略我忽大忽小的字因为这个帖我不熟等我写多些就好了。”说实话这段“免责声明”本身写得挺真诚但阅读体验并没有因此变好。读者并不会因为作者提前打了招呼就觉得这页文字时而大、时而小是正常的更多人只是默默关闭页面。作者说“等我写多些就好了”可真正导致排版混乱的往往不是写得少而是没有在写作流程里解决几件更具体的事情。这些事情拆开来看其实全都有方法可循Markdown 的结构是否正确、编辑器是否统一、有没有固定模板、发布前是否做了检查。这篇博客就从这四个层面把“字忽大忽小”的问题拆解清楚顺便给你一套可以直接复用的写作规范。1. 这篇文章真正要解决的问题先说结论排版忽大忽小的本质不是“字”的问题而是“结构”和“来源”的问题。很多新手作者以为排版混乱是因为自己“写得少”“编辑器用不熟”只要多写几篇自然就好了。这个判断有一定道理但不完全对。写得多确实会让思路更顺畅文字表达更熟练但排版稳定性依赖的是另一套能力——对 Markdown 语法规则的理解以及对“内容从哪里来、编辑器用什么、发布到哪个平台”这些环节的统一管理。举个很常见的场景你在本地编辑器里写文章字和字之间看起来很整齐标题、正文字号比例也舒服。可一旦把内容复制到博客平台并点击发布标题突然不生效了代码块缩进也乱了正文有的行特别大有的行特别小。这种“复制过去就变形”的情况和写作数量没有任何关系本质是编辑器和平台对同一段语法的解析方式不同。所以这篇文章真正要解决的问题是如何基于 Markdown 和一套固定的写作流程让排版从创建草稿到最终发布都保持稳定而不是依赖“多写几篇”去碰运气。适合读这篇文章的人也很明确刚开始写技术博客、团队文档、课程笔记却经常被格式问题打断或者已经在写作但每次发布都要花大量时间手动调字号、调缩进。如果你只是想随手记点笔记不关心排版那本文提到的规范可能有些重但只要你的内容需要被别人阅读排版稳定就是值得投入的一部分。2. “忽大忽小的字”从哪里来排版不稳定的四种来源很多人遇到排版问题第一反应是“平台有问题”或“编辑器有问题”。其实大多数忽大忽小的字都可以归因到下面四种来源。2.1 编辑器与渲染平台不一致不同编辑器对同一篇 Markdown 的渲染结果不完全相同。有的编辑器会自动把“单个换行”当作段落换行有的则要求必须空一行有的编辑器支持自动纠正标题层级有的则保持原样。这就导致你在 A 工具里看到的样子到了 B 平台就会变形。更隐蔽的情况是“预览和发布不一致”。有些平台的编辑器预览窗口和最终文章页面的 CSS 样式并不完全一致预览时觉得字号合适发布后才发现正文字号偏大、代码块又偏小。这种问题不是语法错误却直接影响阅读体验。最稳妥的做法是写作用本地或网页端工具发布前一定用目标平台自带的编辑器打开并确认最终预览。不要拿本地预览当成最终页面的效果。2.2 复制粘贴带来的样式残留这是“字忽大忽小”最经典的来源。比如从 Word、网页或聊天工具里复制一段文字再粘贴到 Markdown 编辑器粘贴的内容可能带着内部样式包括font标签、span标签或固定的font-size属性。Markdown 语法本身是纯文本但很多编辑器的“所见即所得”模式会把这些 HTML 样式一并插入。等发布时这些残留标签会和 Markdown 的默认样式冲突导致某些段落字号异常。你从表面上看到的是“某个地方字变大了”实际看代码会发现里面藏了一串很长的 HTML 标签。2.3 Markdown 语法使用不规范新手最容易踩的坑是混淆标题层级和加粗。比如有人想写一个小标题但用的不是##而是把一句话用**加粗再手动调大字号有人用#写了十几个小标题导致整篇文章的标题层级全部乱掉还有人把“标题”和“正文”之间不空行解析器会认为这是同一段内容导致字号比例不断变化。这些问题的根因是没有把 Markdown 当成一种有语义的结构化语法来用而是把它当成“装饰工具”来用。一旦你开始用#来强调、用**来替代标题排版就会逐渐失序。2.4 图片和代码块宽度不统一图片大小不统一也是排版显乱的重要原因。第一张图是原始尺寸第二张图是压缩后的小图正文宽度就会忽宽忽窄读者会觉得整篇文章“看起来不整齐”。代码块同理有的代码行特别长有的代码行特别短如果编辑器强制换行策略不同代码区的可读性也会下降。这四类问题叠加起来就构成了文章里那些“忽大忽小的字”。解决方案也不是某一个而是需要从工具、模板、语法和发布流程四个方向一起调整。来源典型表现根因解决方向编辑器与平台不一致本地预览正常发布后变形渲染引擎和 CSS 不同发布前用目标平台预览复制粘贴样式残留个别段落字号异常font等 HTML 残留粘贴时选择“纯文本”Markdown 语法不规范标题层级错乱、加粗当标题对语义化语法理解不足使用模板和 lint 检查图片/代码块宽度不一版式忽宽忽窄原始资源尺寸差异统一资源宽度和代码换行3. 核心概念Markdown 为什么能解决排版混乱想解决“忽大忽小”首先得理解 Markdown 到底解决了什么问题。Markdown 是一种轻量级标记语言核心思路是用纯文本的简单符号表达结构例如#表示一级标题##表示二级标题**表示加粗反引号表示行内代码。它的设计目标是“易读易写”让作者不用像写 HTML 那样关注大量标签而是专注于内容本身。3.1 标题的层级是“语义”不是“字号”很多人对标题的理解停留在“标题就是大点的字”。但在 Markdown 里#到######表示的是层级语义一级标题是文章标题二级标题是章节三级标题是子章节。至于它渲染出来是多大字号、什么颜色那是主题和 CSS 的事与内容无关。这个设计有一个非常大的好处当文章复制到不同的平台时只要平台支持标准 Markdown同一个##就会按该平台的标题样式展示。你不需要手动调字号也不需要担心不同平台的字体渲染差异。换句话说只要语义正确排版交给平台统一处理即可。3.2 语法一致性比编辑器功能更重要市面上很多编辑器都有工具栏可以点击插入表格、引用、代码块。这些功能本质上都是在生成 Markdown 符号而不是真正在画布上画一个表格。如果你依赖工具栏插入偶尔手写时符号写错就会出现同一篇文章里两种风格混用。更推荐的做法是在写作前记住最常用的十几个语法符号自己动手写。刚开始会慢一点但习惯之后速度反而不慢而且出错率更低因为你对原文有完全的控制权。3.3 平台差异仍然存在但可以被管理虽然 Markdown 是跨平台的但不同平台对扩展语法——比如表格、任务列表、数学公式、高亮——的支持程度并不完全相同。有的平台支持基于 GFMGitHub Flavored Markdown的扩展语法有的平台则只支持基础语法。因此如果你写的内容要在多个平台发布最好只用所有平台都支持的基础语法如果明确只在某个平台发布再使用该平台支持的扩展功能。这也是为什么“发布前用目标平台预览”是不可避免的一步。本地编辑器解决的是写作体验目标平台解决的是最终效果两者不能互相替代。4. 环境准备一套适合技术写作的本地创作环境要让排版“从开始就稳定”最好的方式是先在本地搭一套统一的写作环境而不是直接打开网页编辑器就敲。下面这套方案以 Visual Studio Code 为例你完全可以使用 Typora、Obsidian 或其他 Markdown 编辑器代替核心思路是本地写、统一配、发布前检查。4.1 安装 VS Code 与 Markdown 支持VS Code 本身对 Markdown 有基础支持包括预览、语法高亮和快捷键。建议再安装两个扩展markdownlint检查 Markdown 语法规范比如标题层级是否跳级、文件末尾是否有空行。Markdown Preview Enhanced提供更丰富的预览能力便于写作时快速查看效果。安装方法是在 VS Code 扩展面板中搜索相关名称点击安装即可。版本以当前较新的稳定版为准。4.2 修改与排版相关的设置如果你的文章经常在“忽大忽小”的边缘徘徊可以先检查 VS Code 里的两处设置编辑器的字体大小和 Markdown 预览字体大小。将它们固定下来可以减少本地预览时的视觉误导。在settings.json中加入以下配置{ editor.fontSize: 16, editor.renderWhitespace: boundary, markdown.preview.fontSize: 16, markdownlint.config: { MD024: false, MD025: false } }说明editor.fontSize编辑区字体大小设为 16px 适合多数高清屏。editor.renderWhitespace显示空格和换行边界便于发现多余空行或多余缩进。markdown.preview.fontSize预览窗口字体大小。markdownlint.config关闭部分严格规则。MD024是“同一标题不能重复”MD025是“只能有一个一级标题”这两条在团队模板中未必适用所以按需关闭。这些设置解决的是“本地看到的效果稳定”避免编辑器和预览两个区域的字号差异过大影响你对排版状态的判断。4.3 统一换行与文件命名文章文件建议统一使用.md后缀编码统一为 UTF-8换行符也尽量一致。Windows 默认换行是 CRLFmacOS/Linux 默认是 LF。如果文件在多个设备之间同步换行符不一致某些编辑器会显示多余空行影响排版判断。固定文件命名规则也有帮助比如YYYY-MM-DD-文章短标题.md。这样在本地目录里能按时间排序也不会因为文件重名覆盖旧稿。5. 从源头固定排版文章模板与写作流程环境搭好之后还需要一套固定的模板。模板能减少你每次从头开始排版的时间也能从结构上避免标题层级错乱。5.1 一个可以直接复制的基础模板下面是一个为技术博客准备的 Markdown 模板覆盖了常见的章节结构。复制后按顺序填充即可# 文章标题 摘要用两三句话说清楚这篇文章解决什么问题、适合谁读。 ## 1. 这篇文章真正要解决的问题 在这一段说明读者会遇到什么痛点以及文章的最终目标。 ## 2. 核心概念与原理 解释文章中出现的名词给出通俗理解和技术定义。 ## 3. 环境准备与前置条件 列出操作系统、依赖版本、工具链和安装步骤。 ## 4. 核心流程拆解 把实现过程拆成步骤每一步说明“做什么”和“为什么”。 ## 5. 完整示例与代码实现 在这里放代码注意标注语言类型。 ## 6. 运行结果与效果验证 说明如何运行、如何验证、如何判断成功。 ## 7. 常见问题与排查思路 用表格列出问题、原因、排查方式和解决方案。 ## 8. 最佳实践与工程建议 给出生产环境中的注意事项和团队协作建议。 ## 9. 总结与后续学习方向 做一些进一步学习的指引落点是具体行动。 --- 转载声明如需转载请联系作者并注明出处。这个模板的优点是标题层级从#到##到###结构清晰不会出现从##直接跳到####的问题。章节编号也方便读者定位。5.2 写作流程建议有了模板之后写作流程可以固定为四步先填充“文章标题”和“摘要”。摘要虽然是开头部分但它往往是在文章写完后才更准确所以可以最后再定稿。按模板的章节顺序写正文。先写核心流程和代码实现再补概念和背景最后写常见问题和最佳实践。写完正文后进入检查阶段重点看标题层级是否跳级、代码块是否闭合、空行是否符合规范。发布到目标平台前复制全文打开目标平台编辑器用“粘贴为纯文本”放入内容再在平台编辑器里补充图片和代码块。如果平台支持“从 Markdown 导入”优先使用导入功能。5.3 图片处理的固定方案图片大小不统一是版式“忽宽忽窄”的重要原因。建议固定两件事第一所有正文配图的宽度尽量一致第二在 Markdown 中避免直接使用原始超清大图可以先用工具统一压缩到合适的宽度再上传。代码块方面尽量设置“自动换行”或“水平滚动”避免超长代码行把页面撑破。多数 Markdown 平台会在代码块内自动处理但本地预览时未必一致所以发布后要看一眼真实效果。6. 完整示例一篇“不会忽大忽小”的 Markdown 文章源码与其单独解释每个规则不如直接看一个完整示例。下面的内容是一篇文章的 Markdown 源码刻意使用了规范语法和统一结构。你可以把它直接复制到本地编辑器里预览# 从排版混乱到稳定输出我的 Markdown 使用规范 摘要很多人写技术文章时会遇到“字忽大忽小”的问题。本文从 Markdown 语法、编辑器配置和发布流程三个角度给出了一套可落地的排版稳定方案。 ## 1. 排版问题的根源 这段内容说明排版混乱通常不是因为写作数量不足而是因为编辑器不统一、语法不规范、复制粘贴携带样式。 ## 2. Markdown 基础语法回顾 ### 2.1 标题 使用 # 到 ###### 表示标题层级。不要用加粗替代标题。 ### 2.2 列表 无序列表使用 -有序列表使用 1.。 ### 2.3 代码块 代码块使用三个反引号包裹并在开头标注语言类型。 ## 3. 本地环境配置 列出编辑器、扩展和相关配置。 ## 4. 写作流程 先大纲再正文最后检查。 ## 5. 发布前检查 发布前使用脚本检查标题层级和空行。 ## 6. 常见问题 使用表格列出。 ## 7. 总结 把规则内化为习惯。你可以对比一下这个示例里没有手动设置任何字号没有font-size没有font标签也没有在标题下面加多余空行。它的排版效果完全交给渲染器因此无论在哪个支持标准 Markdown 的平台都能保持统一、清晰的结构。如果文章里出现了需要自定义字号的极端情况更推荐的做法是修改平台的 CSS 主题而不是在 Markdown 源码里内嵌 HTML 标签。因为 Markdown 的价值恰恰在于纯文本、可迁移、易维护。一旦嵌入太多 HTML 样式可迁移性就会大幅降低。7. 用脚本检查排版格式问题人工检查总有遗漏所以推荐用脚本把“易错项”自动化。下面这个 Python 脚本用于检查 Markdown 文件的标题层级是否跳级、代码块是否闭合。先创建脚本文件# 文件路径scripts/check_markdown_heading.py import re import sys from pathlib import Path def check_headings(file_path: Path) - bool: lines file_path.read_text(encodingutf-8).splitlines() in_code_block False heading_levels [] ok True for line_no, line in enumerate(lines, start1): stripped line.strip() # 标记代码块开始/结束 if stripped.startswith(): in_code_block not in_code_block continue if in_code_block: continue # 匹配 Markdown 标题# 开头后面紧跟一个空格 match re.match(r^(#{1,6})\s, line) if match: level len(match.group(1)) if heading_levels and level heading_levels[-1] 1: print(f[警告] 第 {line_no} 行标题层级跳跃: {stripped}) ok False heading_levels.append(level) if ok: print(标题层级检查通过) return ok if __name__ __main__: if len(sys.argv) 2: print(用法: python check_markdown_heading.py 文件路径) sys.exit(1) sys.exit(0 if check_headings(Path(sys.argv[1])) else 1)然后在项目根目录运行python scripts/check_markdown_heading.py docs/blog-template.md预期输出标题层级检查通过如果文章里从##直接跳到了####脚本会在对应行输出警告并返回非零退出码。这个脚本虽然简单但已经能拦截两类最常见的问题标题跳级和代码块未闭合。还可以用 grep 快速扫描“样式残留”grep -rn font docs/ || echo 未发现 font 标签残留如果输出未发现 font 标签残留说明文章源码里没有从富文本粘贴过来的字体标签排除了“某一行字忽大忽小”的最大嫌疑。8. 常见问题与排查思路下面把实际写作中经常遇到的问题整理成一张表遇到排版异常时可以按表中顺序检查。问题现象可能原因排查方式解决方案发布后标题不生效Markdown 标题前后缺少空行或用了全角 #查看文章源码检查标题行前后是否有空行在标题和正文之间补充空行某一段突然变大或变小粘贴富文本时带入了font或span样式用 grep 搜索font、span复制内容时选择“粘贴为纯文本”删除残留标签代码块没有高亮代码块缺少语言标识或三个反引号不闭合查看代码块首尾是否有对应语言标注在代码块第一行补充语言类型如python、bash本地预览正常发布后格式乱本地编辑器与平台渲染规则不一致用平台编辑器预览一遍发布前在目标平台导入或粘贴并检查最终页面行首出现多余缩进复制时保留了空格或 Tab打开编辑器空白字符观察行首统一去掉行首多余空格使用规范的空行分隔标题层级乱跳章节编号和#数量不匹配运行标题检查脚本修改标题层级确保不跳级图片忽大忽小原始图片宽度不一致或未设置统一比例查看图片在页面中的实际显示宽度统一图片宽度或使用平台支持的尺寸控制表格列的宽度错乱表格缺少分隔行或单元格内容包含竖线检查表格源码的 ---列表间距忽大忽小列表项之间混用空行和换行观察列表项之间是否有多余空行统一列表项之间不空行或统一空行发布后正文两边留白过大段落行数过少平台自动生成大量空白查看 PDF 或阅读视图中的整体版面调整段落结构减少碎片化短行排查时有一个原则先看源码再谈样式。很多排版问题是内容里带着不可见字符或残留标签直接在页面上改很难清除。切到源码模式把问题区域前后各几行的内容完整看一遍往往一眼就能找到原因。9. 最佳实践把排版稳定变成写作习惯排版稳定靠的不是一次两次的修改而是一组可以长期执行的工程化习惯。下面这几点适合个人作者也适合团队文档维护。9.1 文件层用模板和脚本兜底团队写作时建议把 Markdown 模板和检查脚本放进同一个文档仓库。每个成员开始写新文章时都从模板复制写完用脚本检查。这样即使成员对 Markdown 不熟也能在提交阶段被自动化工具拦截大部分格式问题。版本上也建议用 Git 管理不要只依赖网盘或聊天记录传文件。文章出现排版损坏时Git 可以快速对比历史版本知道是哪一次编辑引入了问题。9.2 内容层少用内嵌样式多用语义结构写 Markdown 时尽量不要直接写 HTML。只有在确实无法用 Markdown 表达、且目标平台明确支持的情况下才考虑少量内嵌。否则一律用语义化标题、列表、引用和代码块。图片和附件的宽度尺寸在本地时就统一处理。不要等到发布时在平台页面上手动调平台手动调的结果往往只在该平台生效换一个平台又要重新调一遍。9.3 流程层发布和检查分离写文章和发文章是两件事。写文章时可以用本地编辑器注意力放在内容上发文章时打开目标平台编辑器注意力放在排版效果上。不要一边写一边反复切预览那样既打断思路也容易忽略整体结构问题。发布前的最后一遍检查固定按顺序看三样东西标题层级是否正确章节编号是否连续代码块是否完整语言标注是否正确图片是否加载正常宽度是否协调。9.4 安全与合规提醒写技术文章时注意不要泄露公司内部代码、密钥或未公开的业务信息。引用他人代码或图片时注明来源并确认版权。涉及敏感数据的教程要使用脱敏的示例数据不要直接用生产环境真实数据。这些细节虽然和排版无关但一旦出问题影响远大于一个错字或一张模糊的图。10. 下一步把“写得多了”变成“写得稳了”回到开头那个话题“等我写多些就好了”。这句话真正想表达的可能是“我还不够熟练请给我一点时间”。熟练确实有价值但它应该用来打磨内容的深度、表达的逻辑而不是用来弥补可以被规范和工具解决的排版问题。从今天开始可以尝试做三件事第一把本文的 Markdown 模板复制到本地开始写下一篇技术文章时直接套用。第二安装 markdownlint打开编辑器设置让规范成为写作过程的一部分。第三把检查脚本放进你的写作目录在发布前跑一次。这三件事都不需要等“写多”才能做做完之后你会发现那些忽大忽小的字其实从一开始就是可以被避免的。排版稳定之后读者看到的不再是一篇“作者自己都觉得乱”的文章而是一篇结构清晰、阅读顺畅、值得收藏的内容。这对写作者也是一种正反馈——你不需要在发布前反复调整格式只需要专注于真正重要的部分把技术问题讲清楚。
