“请忽略我忽大忽小的字因为这个帖我不熟等我写多些就好了。”这句话如果出现在开发者社区的帖子开头通常会被当作谦虚的免责声明。但把它放到技术写作流程里看它其实是两个典型的工程信号文字忽大忽小说明排版链路没有被稳定控制“不熟”说明动手之前缺少一条清晰的技术主线。这篇文章从这两个问题出发先解释 Markdown 文档里字体大小为什么会出现波动再给出面对陌生技术主题时如何快速搭建写作主线、跑通最小示例、用版本管理保存验证记录的方法最后整理一份发布前检查清单。读完可以直接套用到日常技术博客写作中特别是需要跨平台发布的 CSDN、博客园和自有博客场景。1. 先搞清楚“忽大忽小的字”是怎么来的才能对症下药1.1 字体大小不是写死在文本里的而是渲染时计算出来的很多人在本地编辑 Markdown 文件时觉得字体大小很正常一旦粘贴到博客后台或社区编辑器里标题变得很大正文很小行内代码忽大忽小。其实 Markdown 本身不保存“字号”这个概念。Markdown 源文件只负责标记语法例如#表示一级标题**粗体**表示加粗最终显示成什么字号要看渲染器把 Markdown 转成 HTML 之后再由浏览器的默认样式或博客主题的 CSS 决定。这就像源码里写了font-size最终页面里却有另一套外部样式覆盖了它。文字忽大忽小本质上是多个渲染环节没有对齐。浏览器对常见的 HTML 标签有默认字体大小。一般规律是h1默认约2emh2默认约1.5em到1.6emh3默认约1.17em到1.3emh4默认约1emp、li、blockquote默认1emcode、pre默认比正文略小常见为0.875em或90%。注意这里的em是相对单位。如果父容器设置了font-size: 20px那么1.5em的标题就会变成30px如果父容器再嵌套一层设置了字体大小标题甚至可能被多次放大。同一个 Markdown 文件在不同平台显示不同很多时候就是因为不同主题给外层容器设置了不同的基础字号。1.2 标题跳级和手写 HTML 标签是最大的“字体不稳定”来源字体忽大忽小的最常见原因有两个。第一个原因标题层级跳级。比如一篇文章开头直接写一个#一级标题随后跳过二级、三级直接用####四级标题承载正文或小标题。四级标题在浏览器里通常和正文差不多大而且很多平台把四级标题渲染得很窄、没有分隔视觉上就会突然从“很大”掉到“很小”。第二个原因在 Markdown 中直接写 HTML 标签例如font size3这段文字大小不确定/font span stylefont-size: 14px;这段文字固定 14px/span这类写法在本地编辑器里可能有效但发布到博客平台后平台可能因为安全策略过滤未知标签、不允许内联样式或者用主题的 CSS 覆盖掉最终出现字号忽大忽小。甚至同一个平台在不同浏览器里表现也不一样。第三个原因编辑器之间的解析规则不同。VS Code、Typora、语雀、博客后台它们对 Markdown 语法的支持并不完全一致。有的支持 CommonMark有的支持 GitHub Flavored Markdown有的还支持自定义扩展。同一段嵌套列表、同一段表格、同一个块级引用在不同渲染器里可能生成不同的 HTML 结构自然也会影响最终字体。1.3 用最小示例复现一次“忽大忽小”先写一个故意制造问题的 Markdown 文件# 技术文章标题 ## 1. 背景 这里是正文。 #### 小标题当正文用 这里也是正文。 font size5这行字会不稳定。/font 普通正文里的 行内代码 通常比正文小。同一个文件放到 Typora、VS Code、博客后台三处预览会看到####小标题和font标签的表现差异较大。为了进一步确认原因可以把渲染后的 HTML 拿出来看看。h1技术文章标题/h1 h21. 背景/h2 p这里是正文。/p h4小标题当正文用/h4 p这里也是正文。/p font size5这行字会不稳定。/font p普通正文里的 code行内代码/code 通常比正文小。/p这个 HTML 里没有统一的字号规则最终字号取决于浏览器默认样式和平台 CSS。h1 和 h4 之间差距很大font size5在 HTML5 里也没有稳定映射关系所以不同环境显示效果完全不同。现场排查时可以打开浏览器开发者工具选中文字后查看 Computed 面板中的font-size和font-family这样能看到最终生效的样式来自哪一行 CSS。写法是右键文字 - 检查 - 选中元素 - 查看 Computed 字体大小。2. 用一套稳定的 Markdown 排版规范把文字大小锁住2.1 先定一个最小排版协议既然文字大小是渲染出来的那么根治方式不是“手写字号”而是约束文档结构和渲染环境。常见项目里可以按这个协议写全站只有一个一级标题通常由博客平台自动生成不要在正文里重复使用#章节标题从##开始子标题从###开始尽量不使用####以下的层级承载正文段落之间必须有空行避免 Markdown 把相邻行合并代码块必须使用带语言标识的围栏代码块例如java不要用缩进代码块处理长代码表格、引用、列表前后都要有空行不在 Markdown 里写font、span等带样式标签禁用内联style文字大小交给 CSS 统一管理不在正文中指定px或em。这样做的好处是同一个 Markdown 文件在本地和线上各平台渲染时结构相对稳定。即使不同平台对默认字号的定义不同也不至于出现同一篇文章里“忽很大、忽很小”的怪象。2.2 字体单位怎么选优先rem而不是em如果你需要维护自己的博客主题或者自定义预览样式字体单位的选择会影响整体是否稳定。px是绝对单位固定、可预期但会忽略用户浏览器的字体设置em是相对单位相对于父元素字号嵌套层级多时容易被反复放大rem是相对根元素html的字号不会随 DOM 嵌套层级变化推荐作为基础字号单位。一份适合技术文档阅读的 CSS 样式可以这样写:root { --base-font-size: 16px; } html { font-size: var(--base-font-size); } body { font-size: 1rem; line-height: 1.75; } h1 { font-size: 2rem; } h2 { font-size: 1.6rem; } h3 { font-size: 1.3rem; } h4 { font-size: 1rem; font-weight: 600; } p, li, blockquote { font-size: 1rem; } code { font-size: 0.9rem; font-family: SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace; } pre { font-size: 0.9rem; line-height: 1.6; padding: 16px; overflow-x: auto; } table { font-size: 0.95rem; }这个样式的关键是正文使用1rem标题使用2rem、1.6rem、1.3rem等比缩放行内代码固定为0.9rem。这样嵌套列表、引用、表格都不会因为父级字号变化而被二次放大或缩小。h4在正文中只承担强调作用字号与正文相同但加粗避免出现“突然变小”。2.3 用 Markdownlint 和编辑器配置阻止“手写字号”只有自觉不够最好让工具在编辑阶段就把问题拦下来。VS Code 里可以安装 Markdownlint 扩展然后在项目根目录添加.markdownlint.json{ MD001: true, MD003: { style: atx }, MD004: { style: sublist }, MD007: { indent: 2 }, MD013: { line_length: 120 }, MD024: false, MD025: false, MD033: { allowed_elements: [details, summary, kbd] } }这里每个配置都有实际含义MD001要求标题层级不能跳级避免出现##后直接####MD003统一标题风格为 ATX 风格也就是##这种散列标记MD004列表统一使用-或统一使用*不要混用MD007列表缩进为 2 个空格避免嵌套列表缩进不一致MD013正文单行长度限制为 120 字符便于后续 diff 和排版MD025不限制文件内只能有一个 H1因为博客平台通常会自动生成文章标题MD033默认禁用 HTML 标签只允许details、summary、kbd这类 Markdown 无法直接表达或必要的标签。在命令行环境下可以用 npx 执行检查npx markdownlint-cli2 docs/**/*.md *.md如果文档中出现了font或spanMarkdownlint 会给出警告。这样能把“字体忽大忽小”拦在发布前而不是上线后才发现。3. 面对“这个帖我不熟”先补技术主线再动笔3.1 “不熟”到底缺什么写作技术文章时说“这个帖我不熟”通常意味着以下几件事至少缺了一项不知道这个技术解决什么问题只能堆名词不清楚依赖环境版本、端口、配置类信息不完整没有跑通过最小示例代码只能是猜测不知道成功结果是什么样写完无法自验证看到报错不知道去哪个环节查排错路径缺失。这些问题不是“写作能力”问题而是缺了一条技术主线。技术主线可以理解成一句话把“是什么、为什么、怎么做、怎么查”串成一个完整闭环。只要这条主线清晰文章自然能组织成可复现的教程。3.2 用五段式把陌生主题拆成可执行任务面对陌生主题推荐先用五段式搭骨架再逐步填内容概念机制用 200 字讲清楚这个技术解决什么问题核心流程是什么。环境准备列出操作系统、依赖软件、版本要求、环境变量、端口号。最小示例写一个能跑通的最小代码项目包含输入、处理、输出。验证结果给出运行命令、预期输出、判断成功的标准。常见问题记录你实际遇到的报错现象、排查方式、修复过程。这个方法的好处是每段只需要回答一个问题。写概念时不需要先写出全部代码写代码时不需要先解释完所有 API。对一个不熟的技术先跑通最小示例再反向补概念比一上来就通读文档更高效。3.3 把“写多些就好了”变成可迭代的写作动作“等我写多些就好了”这句话如果理解成“以后写多了自然就会了”会很难落地。更好的做法是把它变成一个迭代循环版本 0只有标题和五段式骨架版本 1填完环境准备和最小示例能本地复现版本 2补充概念解释和验证结果版本 3加入自己踩过的常见问题版本 4按 Markdownlint 检查和发布前清单修正再发布。每次迭代不需要很大。重点是要保证每一版都能打开、能预览、能看到变化。写作动作可以安排成先建文档目录再写骨架再填代码再跑命令再补日志最后统一排版。创建文档目录时可以用这样一组命令mkdir -p docs/drafts cd docs/drafts touch outline.md environment.md minimal-demo.md verification.md troubleshooting.md这五个文件分别对应五段式。
Markdown排版不稳？从字体大小到陌生主题写作的排查指南
“请忽略我忽大忽小的字因为这个帖我不熟等我写多些就好了。”这句话如果出现在开发者社区的帖子开头通常会被当作谦虚的免责声明。但把它放到技术写作流程里看它其实是两个典型的工程信号文字忽大忽小说明排版链路没有被稳定控制“不熟”说明动手之前缺少一条清晰的技术主线。这篇文章从这两个问题出发先解释 Markdown 文档里字体大小为什么会出现波动再给出面对陌生技术主题时如何快速搭建写作主线、跑通最小示例、用版本管理保存验证记录的方法最后整理一份发布前检查清单。读完可以直接套用到日常技术博客写作中特别是需要跨平台发布的 CSDN、博客园和自有博客场景。1. 先搞清楚“忽大忽小的字”是怎么来的才能对症下药1.1 字体大小不是写死在文本里的而是渲染时计算出来的很多人在本地编辑 Markdown 文件时觉得字体大小很正常一旦粘贴到博客后台或社区编辑器里标题变得很大正文很小行内代码忽大忽小。其实 Markdown 本身不保存“字号”这个概念。Markdown 源文件只负责标记语法例如#表示一级标题**粗体**表示加粗最终显示成什么字号要看渲染器把 Markdown 转成 HTML 之后再由浏览器的默认样式或博客主题的 CSS 决定。这就像源码里写了font-size最终页面里却有另一套外部样式覆盖了它。文字忽大忽小本质上是多个渲染环节没有对齐。浏览器对常见的 HTML 标签有默认字体大小。一般规律是h1默认约2emh2默认约1.5em到1.6emh3默认约1.17em到1.3emh4默认约1emp、li、blockquote默认1emcode、pre默认比正文略小常见为0.875em或90%。注意这里的em是相对单位。如果父容器设置了font-size: 20px那么1.5em的标题就会变成30px如果父容器再嵌套一层设置了字体大小标题甚至可能被多次放大。同一个 Markdown 文件在不同平台显示不同很多时候就是因为不同主题给外层容器设置了不同的基础字号。1.2 标题跳级和手写 HTML 标签是最大的“字体不稳定”来源字体忽大忽小的最常见原因有两个。第一个原因标题层级跳级。比如一篇文章开头直接写一个#一级标题随后跳过二级、三级直接用####四级标题承载正文或小标题。四级标题在浏览器里通常和正文差不多大而且很多平台把四级标题渲染得很窄、没有分隔视觉上就会突然从“很大”掉到“很小”。第二个原因在 Markdown 中直接写 HTML 标签例如font size3这段文字大小不确定/font span stylefont-size: 14px;这段文字固定 14px/span这类写法在本地编辑器里可能有效但发布到博客平台后平台可能因为安全策略过滤未知标签、不允许内联样式或者用主题的 CSS 覆盖掉最终出现字号忽大忽小。甚至同一个平台在不同浏览器里表现也不一样。第三个原因编辑器之间的解析规则不同。VS Code、Typora、语雀、博客后台它们对 Markdown 语法的支持并不完全一致。有的支持 CommonMark有的支持 GitHub Flavored Markdown有的还支持自定义扩展。同一段嵌套列表、同一段表格、同一个块级引用在不同渲染器里可能生成不同的 HTML 结构自然也会影响最终字体。1.3 用最小示例复现一次“忽大忽小”先写一个故意制造问题的 Markdown 文件# 技术文章标题 ## 1. 背景 这里是正文。 #### 小标题当正文用 这里也是正文。 font size5这行字会不稳定。/font 普通正文里的 行内代码 通常比正文小。同一个文件放到 Typora、VS Code、博客后台三处预览会看到####小标题和font标签的表现差异较大。为了进一步确认原因可以把渲染后的 HTML 拿出来看看。h1技术文章标题/h1 h21. 背景/h2 p这里是正文。/p h4小标题当正文用/h4 p这里也是正文。/p font size5这行字会不稳定。/font p普通正文里的 code行内代码/code 通常比正文小。/p这个 HTML 里没有统一的字号规则最终字号取决于浏览器默认样式和平台 CSS。h1 和 h4 之间差距很大font size5在 HTML5 里也没有稳定映射关系所以不同环境显示效果完全不同。现场排查时可以打开浏览器开发者工具选中文字后查看 Computed 面板中的font-size和font-family这样能看到最终生效的样式来自哪一行 CSS。写法是右键文字 - 检查 - 选中元素 - 查看 Computed 字体大小。2. 用一套稳定的 Markdown 排版规范把文字大小锁住2.1 先定一个最小排版协议既然文字大小是渲染出来的那么根治方式不是“手写字号”而是约束文档结构和渲染环境。常见项目里可以按这个协议写全站只有一个一级标题通常由博客平台自动生成不要在正文里重复使用#章节标题从##开始子标题从###开始尽量不使用####以下的层级承载正文段落之间必须有空行避免 Markdown 把相邻行合并代码块必须使用带语言标识的围栏代码块例如java不要用缩进代码块处理长代码表格、引用、列表前后都要有空行不在 Markdown 里写font、span等带样式标签禁用内联style文字大小交给 CSS 统一管理不在正文中指定px或em。这样做的好处是同一个 Markdown 文件在本地和线上各平台渲染时结构相对稳定。即使不同平台对默认字号的定义不同也不至于出现同一篇文章里“忽很大、忽很小”的怪象。2.2 字体单位怎么选优先rem而不是em如果你需要维护自己的博客主题或者自定义预览样式字体单位的选择会影响整体是否稳定。px是绝对单位固定、可预期但会忽略用户浏览器的字体设置em是相对单位相对于父元素字号嵌套层级多时容易被反复放大rem是相对根元素html的字号不会随 DOM 嵌套层级变化推荐作为基础字号单位。一份适合技术文档阅读的 CSS 样式可以这样写:root { --base-font-size: 16px; } html { font-size: var(--base-font-size); } body { font-size: 1rem; line-height: 1.75; } h1 { font-size: 2rem; } h2 { font-size: 1.6rem; } h3 { font-size: 1.3rem; } h4 { font-size: 1rem; font-weight: 600; } p, li, blockquote { font-size: 1rem; } code { font-size: 0.9rem; font-family: SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace; } pre { font-size: 0.9rem; line-height: 1.6; padding: 16px; overflow-x: auto; } table { font-size: 0.95rem; }这个样式的关键是正文使用1rem标题使用2rem、1.6rem、1.3rem等比缩放行内代码固定为0.9rem。这样嵌套列表、引用、表格都不会因为父级字号变化而被二次放大或缩小。h4在正文中只承担强调作用字号与正文相同但加粗避免出现“突然变小”。2.3 用 Markdownlint 和编辑器配置阻止“手写字号”只有自觉不够最好让工具在编辑阶段就把问题拦下来。VS Code 里可以安装 Markdownlint 扩展然后在项目根目录添加.markdownlint.json{ MD001: true, MD003: { style: atx }, MD004: { style: sublist }, MD007: { indent: 2 }, MD013: { line_length: 120 }, MD024: false, MD025: false, MD033: { allowed_elements: [details, summary, kbd] } }这里每个配置都有实际含义MD001要求标题层级不能跳级避免出现##后直接####MD003统一标题风格为 ATX 风格也就是##这种散列标记MD004列表统一使用-或统一使用*不要混用MD007列表缩进为 2 个空格避免嵌套列表缩进不一致MD013正文单行长度限制为 120 字符便于后续 diff 和排版MD025不限制文件内只能有一个 H1因为博客平台通常会自动生成文章标题MD033默认禁用 HTML 标签只允许details、summary、kbd这类 Markdown 无法直接表达或必要的标签。在命令行环境下可以用 npx 执行检查npx markdownlint-cli2 docs/**/*.md *.md如果文档中出现了font或spanMarkdownlint 会给出警告。这样能把“字体忽大忽小”拦在发布前而不是上线后才发现。3. 面对“这个帖我不熟”先补技术主线再动笔3.1 “不熟”到底缺什么写作技术文章时说“这个帖我不熟”通常意味着以下几件事至少缺了一项不知道这个技术解决什么问题只能堆名词不清楚依赖环境版本、端口、配置类信息不完整没有跑通过最小示例代码只能是猜测不知道成功结果是什么样写完无法自验证看到报错不知道去哪个环节查排错路径缺失。这些问题不是“写作能力”问题而是缺了一条技术主线。技术主线可以理解成一句话把“是什么、为什么、怎么做、怎么查”串成一个完整闭环。只要这条主线清晰文章自然能组织成可复现的教程。3.2 用五段式把陌生主题拆成可执行任务面对陌生主题推荐先用五段式搭骨架再逐步填内容概念机制用 200 字讲清楚这个技术解决什么问题核心流程是什么。环境准备列出操作系统、依赖软件、版本要求、环境变量、端口号。最小示例写一个能跑通的最小代码项目包含输入、处理、输出。验证结果给出运行命令、预期输出、判断成功的标准。常见问题记录你实际遇到的报错现象、排查方式、修复过程。这个方法的好处是每段只需要回答一个问题。写概念时不需要先写出全部代码写代码时不需要先解释完所有 API。对一个不熟的技术先跑通最小示例再反向补概念比一上来就通读文档更高效。3.3 把“写多些就好了”变成可迭代的写作动作“等我写多些就好了”这句话如果理解成“以后写多了自然就会了”会很难落地。更好的做法是把它变成一个迭代循环版本 0只有标题和五段式骨架版本 1填完环境准备和最小示例能本地复现版本 2补充概念解释和验证结果版本 3加入自己踩过的常见问题版本 4按 Markdownlint 检查和发布前清单修正再发布。每次迭代不需要很大。重点是要保证每一版都能打开、能预览、能看到变化。写作动作可以安排成先建文档目录再写骨架再填代码再跑命令再补日志最后统一排版。创建文档目录时可以用这样一组命令mkdir -p docs/drafts cd docs/drafts touch outline.md environment.md minimal-demo.md verification.md troubleshooting.md这五个文件分别对应五段式。
