刚整理旧笔记的时候翻了去年写的一批 Markdown 文档说实话有点看不下去。不是内容不行是排版太随意标题层级乱跳加粗滥用图片有大有小还带着一长串链接地址代码块没有语言标注整篇看下来像一份草稿。那阵子我突然意识到Markdown 常用技巧不在于学多少而在于怎么用才让笔记真正美观、耐读。花了两周时间重新整理自己的排版习惯这篇就把我沉淀下来的几个关键技巧一次性说透适合写技术笔记、课程记录、博客草稿的人也适合那些明明在用 Typora 或笔记软件但成品总差口气的朋友。1. 为什么你的 Markdown 笔记总是不好看1.1 三个让我决定重写笔记排版的因素先说我的实际经历方便你对号入座。第一个因素是笔记数量上去之后回看旧文档的“后悔感”越来越强。写的时候不觉得乱等一个月后再翻标题层级混乱的文档根本没法快速定位内容恨不得重写一遍。第二个因素是我在不同的编辑器里打开同一份文档渲染出来的效果差异很大。有些 Markdown 扩展语法在 A 编辑器显示得很精致到了 B 平台就直接失灵表格错位、换行消失、图片变形整篇笔记的观感瞬间崩塌。第三个因素是“花哨”和“美观”被我搞混了很久。有一阵子我疯狂使用各种强调标记、引用嵌套、多彩文字以为视觉效果丰富就是好看实际结果恰恰相反。一份笔记里到处都是加粗和删除线读者的视线根本不知道该落哪儿。后来我才想明白Markdown 的美观本质上是一种克制——层级清楚、留白合理、重点突出远胜过堆砌一堆花活。1.2 先弄懂底层逻辑Markdown 的美观来自“语义化”书写很多教程会教你记语法却不讲原理导致你学了一堆技巧却不知道什么时候用。Markdown 的核心逻辑其实特别简单你写的是“结构”不是“样式”。标题就是标题引用就是引用列表就是列表至于它们最终显示成什么字形、什么颜色、什么大小是由渲染引擎和主题样式决定的。换句话说同一份 Markdown 文档在不同软件里长得不一样这不是 bug而是机制本身如此。你唯一能控制的是让自己的书写符合规范、语义准确。这个认知转变很关键当你不再纠结于“我的标题能不能变成红色”而是关心“我的笔记结构是不是清晰”很多排版问题就迎刃而解了。所以我的建议是在掌握技巧之前先确定一个统一的编辑环境并固定下来。后续所有的预览效果、样式微调都基于这个环境进行。我自己日常用的是本地编辑器加在线文档平台双备份以本地编辑器的渲染为准写完再剪切到其他平台检查兼容性。2. 正文排版的地基标题、引用、列表的“克制美学”2.1 标题层级统一一篇文章只有一个一级大标题标题是笔记的骨架也是大多数人最容易犯错的地方。很多新手写着写着会把#和##混着用这篇文章的主标题用了##下一篇文章主标题用了#同一篇文章里##下面出现了###然后再出现一个独立的##。层级跳跃的结果是生成目录时一片混乱折叠功能也形同虚设。我的使用纪律很简单一篇笔记只有一个#一级标题它就是整篇文档的名称##是文章的一级章节通常控制在三到六个之间###是二级小节只在必要时使用原则上不会出现####及更深层级的标题。如果内容确实需要更深层级我会考虑把文档拆分而不是继续嵌套。这样做的好处非常直观。头部标题清晰目录生成后可以一眼看清全文结构侧边栏导航的折叠逻辑也顺畅阅读者能快速跳转到自己关心的章节。记住一点Markdown 的标题不是给你自己看着方便的而是给读者建立认知路径用的。2.2 加粗、斜体与删除线按需使用而不是到处撒加粗、斜体和删除线是最常用的行内强调语法。问题也随之而来很多人写笔记时习惯性地把所有自认为重要的词都加上加粗结果整篇文章看起来像在吵架。我给自己定了一个“频率上限”单个段落里加粗的词不超过两到三处全文重要的概念用加粗标注关键的操作步骤可以用加粗强调但不要在同一句话里叠加加粗和斜体。斜体的使用场景更窄我通常只用来表示外来术语、书名、或者语气上的轻微强调。比如常规文档中“这种做法的原理是 X”斜体的使用在视觉上不会产生强烈的提示效果但能让读者注意到某个微妙的区别。删除线我基本只在协作场景下用表示内容已废弃但仍保留备查或者标记某项任务不再需要处理。在个人笔记里删除线用得越少越好——它会让读者频繁回头确认反而打断阅读节奏。按需使用强调标记比一次性堆满更有效果。因为加粗的本质是“让视觉落脚点减少”你到处都加重等于没有重点。2.3 引用块把“旁白”和“正文”分隔开引用块的样式在很多主题里渲染得很有质感——通常有背景色、左侧有边界条天然适合用来放置跟正文内容不同性质的补充信息。我常把引用块用在三类场景第一类是“注意事项”比如可能造成错误操作的关键提示第二类是“背景说明”补充某些概念或者讲清楚来龙去脉第三类是“个人批注”记录自己的感想、结论或者对某段文字的评论。这里有个容易踩的坑引用块不是用来摘抄大段文字的工具。如果引用内容超过三行正文的结构感就会被打破整篇笔记像是一串嵌套的引用盒子。建议每次引用控制在三行以内需要长篇引用时提炼核心观点再加引用或者使用折叠块收起来。引用块里的换行也有讲究。Markdown 标准语法里引用的每一行最好都加上有些编辑器会自动处理但如果你手动整理记得保持每行一个否则在某些严格解析器里出现段落断裂。2.4 列表层级别超过两层嵌套不如重写列表是记笔记时最高频使用的语法但也是最容易被用烂的。典型的错误是无序列表嵌套三层以上看完之后完全分不清层级归属。我的经验是嵌套组合最好不要超过两层。第一层放主题第二层放细节如果有更细的内容要么把它合并到第二层的正文里要么改写成一小段话。列表的作用是“快速扫读”一旦层级复杂扫读效率反而下降。有序列表和无序列表的使用也要区分。有序列表一定用于有先后顺序的操作步骤、流程环节而无序列表用于并列的信息点、特性列举、条件说明。混用的结果往往是读者以为内容有先后顺序实际读下来却是平铺的信息。另外还要注意列表标记符的统一。很多人会把-、、*混着用这不会导致渲染失败但会让源代码非常凌乱。建议固定使用一个符号——我自己选的是-因为它不太容易误输入。3. 图片、链接、代码块里藏着最多“廉价感”3.1 图片尺寸、对齐和说明文字决定质感图片处理是很多人忽略的重灾区。默认插入图片的方式虽然简单但成品往往不够精致图片在整宽布局下被拉伸变形或者因为尺寸不一而参差不齐。我目前的标准做法是图片一律使用相对路径或稳定的图床地址图片宽度控制在页面宽度的三分之二以内。具体实现有两种方式一种是在 Markdown 语法里直接用另一种是用 HTML 的img标签控制尺寸img src./images/example.png width600 alt示意图描述 /第二种方式在大多数支持 HTML 的编辑器中都能生效适合需要统一图片宽度时使用。需要注意alt属性别留空它一方面有助于无障碍阅读另一方面在图片加载失败时显示的文字能保持上下文不会因为一张裂图毁了整个排版。图片说明文字同样重要。单纯的图片没有上下文读者不知道看什么。建议在图下方增加一行不加粗、字号被缩小的说明文字通常用引用块或普通斜体实现。例如图 1三种标题层级的目录对比示意这张“编号 说明”的格式在技术笔记里尤其能提升专业感。3.2 链接长 URL 的阅读污染另一个常见问题是长 URL 直接粘在正文里。在一篇笔记里出现三五个上百字符的链接视觉上极其割裂读者扫读的时候很容易卡在这些乱码一样的长串上。Markdown 的标准语法其实已经给了解决方案[Markdown 官方教程](https://example.com/markdown-guide)这样处理后正文区域只显示链接文字干净清爽。但实际操作中很多人还是偷懒直接粘贴 URL我怀疑是没养成顺手写链接文字的习惯。这里有个小技巧复制网址后先想一下这个链接是给读者提供什么信息的然后用三到五个字描述它再粘进语法结构里。链接特别多时还可以把它们统一放到文档末尾的“参考链接”区块[链接文字](https://example.com) [另一个链接文字](https://example.net)或者用定义的写法同一链接多次引用时不重复粘贴地址。这样正文完全不受长 URL 干扰底部的链接列表反而变成了一种附录式的资源库阅读体验非常舒服。3.3 代码块语言标注和行内代码不要滥用代码块是技术笔记的刚需但美观的关键不在于代码本身而在于你是否给了它合适的呈现方式。首先代码块必须标注语言不只是让渲染器做语法高亮更是让读者提前知道这段代码是什么。例如python print(hello world) 语言标注缺失时代码块虽然也能渲染但完全没有高亮在长段落里视觉上更难读。我也见过有人给所有代码块统一标text如果是日志内容、配置片段还说得过去但真正的代码段建议按实际语言标注高亮效果差别非常大。其次是行内代码的滥用。不少人有这个习惯正文里出现任何文件名、变量名、命令统统用反引号包起来。如果只是少量出现确实能提升辨识度但如果一段话里出现六七个反引号读者会感觉像在阅读代码文档而不是笔记反而丢失了重点。我的规则是只有真正的代码标识符、命令、文件路径、函数名才使用行内代码概念名词、普通的强调内容均用加粗或斜体处理。这样行内代码就天然带上了“机器语言”的信号不会和普通文本混淆。4. 表格与数学公式提升专业感但要把握好度4.1 表格对齐方式与内容排序的价值表格是 Markdown 里最容易被误用、也最能提升专业感的一个语法。很多人会写表格基本语法但很少关心对齐方式和内容组织。基本语法很好理解| 项目 | 数量 | 备注 | | :------ | :--: | ------- | | 苹果 | 3 | 已清洗 | | 香蕉 | 5 | 已去皮 |注意到第二行的冒号位置——它决定了整列的对齐方式。:---表示左对齐:---:表示居中---:表示右对齐。默认情况下表格内容一律左对齐但当你需要对齐数字、状态标记时适当使用居中和右对齐会让表格更清晰。关于表格内容有一点务必注意单元格里的文字不要写太多。一个单元格超过三行表格就会变得臃肿阅读体验直线下降。如果确实需要大段描述把表格拆成两列或者在表格下方补一段补充说明。表格的美观还依赖内容的排序逻辑。经常看到有人把“重要程度”不同的内容混在一起顺序完全随缘。我的习惯是如果表格表达的是多个方案的对比就让列顺序保持“方案名称、关键参数、优劣比较、适用场景”这样的递进如果是数据罗列就按时间、数值大小、优先级排序。排序看似不起眼却是读者理解表格的第一线索。4.2 数学公式与脚注长文档的加分项如果你经常记理工科笔记数学公式几乎是绕不开的。基于 LaTeX 语法渲染公式的功能在很多编辑器中已经普及效果相当专业。行内公式用$...$包裹比如 $E mc^2$独立成行的公式用$$...$$包裹$$ \int_0^1 x^2 dx \frac{1}{3} $$公式的美观点在两个地方一是公式与正文之间留出空行让块级公式不完全嵌入段落文字二是公式中统一使用标准的数学变量斜体风格不要混用中文与公式符号。脚注是我个人非常喜欢的功能它能把补充说明和引用来源从正文中优雅地剥离出来。语法也不复杂在正文里写上内容[^1]。 [^1]: 补充解释或者出处的说明。脚注用好了整篇笔记的正文会更干净那些“这话怎么说”“哪来的数据”之类的旁逸内容都有了合适的去处。尤其是长文档脚注几乎是从好看到专业的必经之路。5. 进阶美化HTML 兜底、分隔线与折叠块5.1 什么时候需要用 HTML 兜底标准 Markdown 语法能覆盖绝大多数场景但有几个情况它处理不了比如精准控制图片尺寸、内容居中、设置颜色、调整行间距等。这时候就得让 HTML 标签兜底。Markdown 本身允许内嵌 HTML所以你可以直接写出这样的居中段落div styletext-align:center b这段话会居中显示/b /divcenter老式写法在部分平台兼容性差不建议使用/center居中、原色文字、自定义字号这些 HTML 标签虽然强大但有两个副作用一是降低了源代码的可移植性换到不支持内联样式的平台效果会失效二是破坏视觉纯净度科技笔记如果大量出现彩色文字和特殊居中整体风格容易走偏。我的原则是能用标准 Markdown 语法解决的场景绝不用 HTML只有图片尺寸、极少量的居中对齐、特殊字体这几个非用它不可的场景才考虑。而且尽量通过编辑器的“自定义样式”或主题统一处理而不是在每一篇文章里手写一堆style字符串。5.2 分隔线少即是多分隔线是一把双刃剑。适度使用能帮助读者感知章节之间的停顿特殊主题下还能充当审美符号但用得太多整页全是横向线条非常廉价。我一般只在以下情况使用分隔线正文中两个大主题切换、从说明区进入代码案例区、文档开头进入正文。规则是全文最多不超过三到五条。段落内部需要分隔时优先考虑用标题层级或列表结构表达而不是画一条线强行切分。还有一种情况是文档内部的锚点跳转现在不少编辑器支持生成目录但也有人喜欢在文章内写“点击跳转”。这种场景用标准 Markdown 的链接语法即可[跳转到第 3 节](#3-进阶美化html兜底分隔线与折叠块)注意标题转成锚点时一般遵循“去空格、大写转小写、去掉标点”规则不同平台略有差异最好实测确认。5.3 折叠块把信息藏得恰到好处折叠块是进阶排版里性价比很高的一项技能尤其适合“答案”型内容。你可以在笔记里先抛出问题让读者思考然后提供一个折叠区域点击展开就能看到参考实现和详细说明。标准 Markdown 不直接支持折叠但绝大多数现代笔记类编辑器都兼容 HTML 的details和summary标签写法也比较简单details summary点击查看参考答案/summary 这里是折叠的内容可以是文字、列表甚至代码块。 /details用折叠块的好处非常明显它让文档的信息密度可控。读者根据自己的需求决定展开哪些内容页面不会一开始就显得拥挤不堪。我的使用场景包括题目的详细解答、长代码段、额外参考资料的列表、不太重要但偶尔需要查看的历史说明。折叠块虽然好用也别滥用。如果一个页面里有七八个折叠块视觉上全是框框反而显得零碎。我建议一篇笔记最多安排三到五个确保百分之八十的内容在默认状态下是直接可见的否则读者会失去阅读耐心。6. 不同编辑器下的“同文不同颜”兼容性与书写习惯6.1 主流编辑器的渲染差异对照很多人在某个编辑器里排得特别舒服换到另一个平台就全线崩溃。这不是你的操作问题而是 Markdown 生态的天然现状。为了帮你减少意外我整理了一份常见差异对照表渲染能力本地编辑器在线文档平台代码托管平台标准 Markdown 语法支持支持支持上下标扩展不一致多数支持部分支持表格进阶功能合并单元格等多数不支持视平台而定多数不支持数学公式多数支持部分支持支持HTML 内嵌支持部分允许支持有限脚注多数编辑器支持部分支持部分支持从表格能看出来真正稳定可靠的其实是标准语法。扩展语法虽然能带来额外表现力但也意味着兼容性风险。6.2 换行规则两个空格与一个空行的战争换行是 Markdown 使用中最容易让人困惑的点也直接决定成品排版是否整齐。标准 Markdown 的硬换行要求行尾加两个空格再按回车才能看到换行效果。但大多数现代笔记编辑器已经做了折中处理直接按一次回车也能换行而在某些严格渲染环境里回车键造成的只是段内软换行视觉上仍跟上一行连在一起。我之前在同一份文档里混用了两种习惯导致在某个平台上有一段文字挤成了一整行。排查了半天才意识到是换行规则不同。后来我给自己的统一方案是段落之间一律用空行分隔即写完一段后按两次回车段落内部的强制换行尽量少用遇到需要列举多个短句时直接改用列表或引用块来组织。还有一个相关细节不要用多个连续的空行来制造“留白”。Markdown 连续空行会折叠成一个而且在不同平台表现不同用多空行制造间距的做法基本是白费力气。真想控制段间距应该在编辑器自带的样式或主题里设置而不是在内容里敲回车。6.3 我的兼容策略建立一份个人排版规范经历了不同平台间的格式翻车之后我现在形成了一套自己的排版规范。这套规范的所有条款都基于一个核心只用标准语法 少量必需的 HTML 兜底保证大概率兼容。具体来说我的规范是这样标题层级严格执行一级到三级不出现更深层级强调标记每段不超过三处加粗和斜体不同时使用引用块控制在三行内用途明确为提示或旁白列表最多两层固定使用-做无序列表标记图片都设置合理宽度并配有图注说明代码块一定标注语言行内代码只用于真正的代码术语表格中对齐方式与内容排序在做完表格后单独检查一遍文档末尾统一附参考链接区块正文中不出现裸链接数学公式只在使用它确实提升表达效率的场景下使用折叠块不超过五个且绝大多数内容默认可见在建这套规范之前我每次写完笔记都要花不少时间在细节调整上。建完之后排版时间大幅度缩短成品稳定度也明显上升。遇到特殊情况我会先把特殊写法在目标平台上快速测试一遍再决定是否纳入正文。结尾最后分享一个我实测很管用的小技巧每写完一篇笔记花两分钟只看“目录大纲”和“代码块列表”把页面滚一遍模拟读者扫读的节奏。如果这期间你看到了任何让你皱眉的地方——标题层级乱了、某段加粗太扎眼、图片大小不一致、表格挤成一团——立刻修正不要拖。这个方法把排版问题从“整体感觉”变成“具体节点”效率极高。当然Markdown 美观的标准永远会随着工具和审美变化所以不必追求一次到位。把上面这些常用技巧沉淀成自己的默认习惯你的每一篇笔记都会有一个稳定的底线然后在这个底线之上慢慢形成个人风格。真正实用的方案永远是自己用着顺手、读者读着舒服的那一套。 
长河君 · 2026/10/24 1:25:27 · 阅读 1.2k Markdown排版进阶：从语义化书写到稳定美观的笔记规范
刚整理旧笔记的时候翻了去年写的一批 Markdown 文档说实话有点看不下去。不是内容不行是排版太随意标题层级乱跳加粗滥用图片有大有小还带着一长串链接地址代码块没有语言标注整篇看下来像一份草稿。那阵子我突然意识到Markdown 常用技巧不在于学多少而在于怎么用才让笔记真正美观、耐读。花了两周时间重新整理自己的排版习惯这篇就把我沉淀下来的几个关键技巧一次性说透适合写技术笔记、课程记录、博客草稿的人也适合那些明明在用 Typora 或笔记软件但成品总差口气的朋友。1. 为什么你的 Markdown 笔记总是不好看1.1 三个让我决定重写笔记排版的因素先说我的实际经历方便你对号入座。第一个因素是笔记数量上去之后回看旧文档的“后悔感”越来越强。写的时候不觉得乱等一个月后再翻标题层级混乱的文档根本没法快速定位内容恨不得重写一遍。第二个因素是我在不同的编辑器里打开同一份文档渲染出来的效果差异很大。有些 Markdown 扩展语法在 A 编辑器显示得很精致到了 B 平台就直接失灵表格错位、换行消失、图片变形整篇笔记的观感瞬间崩塌。第三个因素是“花哨”和“美观”被我搞混了很久。有一阵子我疯狂使用各种强调标记、引用嵌套、多彩文字以为视觉效果丰富就是好看实际结果恰恰相反。一份笔记里到处都是加粗和删除线读者的视线根本不知道该落哪儿。后来我才想明白Markdown 的美观本质上是一种克制——层级清楚、留白合理、重点突出远胜过堆砌一堆花活。1.2 先弄懂底层逻辑Markdown 的美观来自“语义化”书写很多教程会教你记语法却不讲原理导致你学了一堆技巧却不知道什么时候用。Markdown 的核心逻辑其实特别简单你写的是“结构”不是“样式”。标题就是标题引用就是引用列表就是列表至于它们最终显示成什么字形、什么颜色、什么大小是由渲染引擎和主题样式决定的。换句话说同一份 Markdown 文档在不同软件里长得不一样这不是 bug而是机制本身如此。你唯一能控制的是让自己的书写符合规范、语义准确。这个认知转变很关键当你不再纠结于“我的标题能不能变成红色”而是关心“我的笔记结构是不是清晰”很多排版问题就迎刃而解了。所以我的建议是在掌握技巧之前先确定一个统一的编辑环境并固定下来。后续所有的预览效果、样式微调都基于这个环境进行。我自己日常用的是本地编辑器加在线文档平台双备份以本地编辑器的渲染为准写完再剪切到其他平台检查兼容性。2. 正文排版的地基标题、引用、列表的“克制美学”2.1 标题层级统一一篇文章只有一个一级大标题标题是笔记的骨架也是大多数人最容易犯错的地方。很多新手写着写着会把#和##混着用这篇文章的主标题用了##下一篇文章主标题用了#同一篇文章里##下面出现了###然后再出现一个独立的##。层级跳跃的结果是生成目录时一片混乱折叠功能也形同虚设。我的使用纪律很简单一篇笔记只有一个#一级标题它就是整篇文档的名称##是文章的一级章节通常控制在三到六个之间###是二级小节只在必要时使用原则上不会出现####及更深层级的标题。如果内容确实需要更深层级我会考虑把文档拆分而不是继续嵌套。这样做的好处非常直观。头部标题清晰目录生成后可以一眼看清全文结构侧边栏导航的折叠逻辑也顺畅阅读者能快速跳转到自己关心的章节。记住一点Markdown 的标题不是给你自己看着方便的而是给读者建立认知路径用的。2.2 加粗、斜体与删除线按需使用而不是到处撒加粗、斜体和删除线是最常用的行内强调语法。问题也随之而来很多人写笔记时习惯性地把所有自认为重要的词都加上加粗结果整篇文章看起来像在吵架。我给自己定了一个“频率上限”单个段落里加粗的词不超过两到三处全文重要的概念用加粗标注关键的操作步骤可以用加粗强调但不要在同一句话里叠加加粗和斜体。斜体的使用场景更窄我通常只用来表示外来术语、书名、或者语气上的轻微强调。比如常规文档中“这种做法的原理是 X”斜体的使用在视觉上不会产生强烈的提示效果但能让读者注意到某个微妙的区别。删除线我基本只在协作场景下用表示内容已废弃但仍保留备查或者标记某项任务不再需要处理。在个人笔记里删除线用得越少越好——它会让读者频繁回头确认反而打断阅读节奏。按需使用强调标记比一次性堆满更有效果。因为加粗的本质是“让视觉落脚点减少”你到处都加重等于没有重点。2.3 引用块把“旁白”和“正文”分隔开引用块的样式在很多主题里渲染得很有质感——通常有背景色、左侧有边界条天然适合用来放置跟正文内容不同性质的补充信息。我常把引用块用在三类场景第一类是“注意事项”比如可能造成错误操作的关键提示第二类是“背景说明”补充某些概念或者讲清楚来龙去脉第三类是“个人批注”记录自己的感想、结论或者对某段文字的评论。这里有个容易踩的坑引用块不是用来摘抄大段文字的工具。如果引用内容超过三行正文的结构感就会被打破整篇笔记像是一串嵌套的引用盒子。建议每次引用控制在三行以内需要长篇引用时提炼核心观点再加引用或者使用折叠块收起来。引用块里的换行也有讲究。Markdown 标准语法里引用的每一行最好都加上有些编辑器会自动处理但如果你手动整理记得保持每行一个否则在某些严格解析器里出现段落断裂。2.4 列表层级别超过两层嵌套不如重写列表是记笔记时最高频使用的语法但也是最容易被用烂的。典型的错误是无序列表嵌套三层以上看完之后完全分不清层级归属。我的经验是嵌套组合最好不要超过两层。第一层放主题第二层放细节如果有更细的内容要么把它合并到第二层的正文里要么改写成一小段话。列表的作用是“快速扫读”一旦层级复杂扫读效率反而下降。有序列表和无序列表的使用也要区分。有序列表一定用于有先后顺序的操作步骤、流程环节而无序列表用于并列的信息点、特性列举、条件说明。混用的结果往往是读者以为内容有先后顺序实际读下来却是平铺的信息。另外还要注意列表标记符的统一。很多人会把-、、*混着用这不会导致渲染失败但会让源代码非常凌乱。建议固定使用一个符号——我自己选的是-因为它不太容易误输入。3. 图片、链接、代码块里藏着最多“廉价感”3.1 图片尺寸、对齐和说明文字决定质感图片处理是很多人忽略的重灾区。默认插入图片的方式虽然简单但成品往往不够精致图片在整宽布局下被拉伸变形或者因为尺寸不一而参差不齐。我目前的标准做法是图片一律使用相对路径或稳定的图床地址图片宽度控制在页面宽度的三分之二以内。具体实现有两种方式一种是在 Markdown 语法里直接用另一种是用 HTML 的img标签控制尺寸img src./images/example.png width600 alt示意图描述 /第二种方式在大多数支持 HTML 的编辑器中都能生效适合需要统一图片宽度时使用。需要注意alt属性别留空它一方面有助于无障碍阅读另一方面在图片加载失败时显示的文字能保持上下文不会因为一张裂图毁了整个排版。图片说明文字同样重要。单纯的图片没有上下文读者不知道看什么。建议在图下方增加一行不加粗、字号被缩小的说明文字通常用引用块或普通斜体实现。例如图 1三种标题层级的目录对比示意这张“编号 说明”的格式在技术笔记里尤其能提升专业感。3.2 链接长 URL 的阅读污染另一个常见问题是长 URL 直接粘在正文里。在一篇笔记里出现三五个上百字符的链接视觉上极其割裂读者扫读的时候很容易卡在这些乱码一样的长串上。Markdown 的标准语法其实已经给了解决方案[Markdown 官方教程](https://example.com/markdown-guide)这样处理后正文区域只显示链接文字干净清爽。但实际操作中很多人还是偷懒直接粘贴 URL我怀疑是没养成顺手写链接文字的习惯。这里有个小技巧复制网址后先想一下这个链接是给读者提供什么信息的然后用三到五个字描述它再粘进语法结构里。链接特别多时还可以把它们统一放到文档末尾的“参考链接”区块[链接文字](https://example.com) [另一个链接文字](https://example.net)或者用定义的写法同一链接多次引用时不重复粘贴地址。这样正文完全不受长 URL 干扰底部的链接列表反而变成了一种附录式的资源库阅读体验非常舒服。3.3 代码块语言标注和行内代码不要滥用代码块是技术笔记的刚需但美观的关键不在于代码本身而在于你是否给了它合适的呈现方式。首先代码块必须标注语言不只是让渲染器做语法高亮更是让读者提前知道这段代码是什么。例如python print(hello world) 语言标注缺失时代码块虽然也能渲染但完全没有高亮在长段落里视觉上更难读。我也见过有人给所有代码块统一标text如果是日志内容、配置片段还说得过去但真正的代码段建议按实际语言标注高亮效果差别非常大。其次是行内代码的滥用。不少人有这个习惯正文里出现任何文件名、变量名、命令统统用反引号包起来。如果只是少量出现确实能提升辨识度但如果一段话里出现六七个反引号读者会感觉像在阅读代码文档而不是笔记反而丢失了重点。我的规则是只有真正的代码标识符、命令、文件路径、函数名才使用行内代码概念名词、普通的强调内容均用加粗或斜体处理。这样行内代码就天然带上了“机器语言”的信号不会和普通文本混淆。4. 表格与数学公式提升专业感但要把握好度4.1 表格对齐方式与内容排序的价值表格是 Markdown 里最容易被误用、也最能提升专业感的一个语法。很多人会写表格基本语法但很少关心对齐方式和内容组织。基本语法很好理解| 项目 | 数量 | 备注 | | :------ | :--: | ------- | | 苹果 | 3 | 已清洗 | | 香蕉 | 5 | 已去皮 |注意到第二行的冒号位置——它决定了整列的对齐方式。:---表示左对齐:---:表示居中---:表示右对齐。默认情况下表格内容一律左对齐但当你需要对齐数字、状态标记时适当使用居中和右对齐会让表格更清晰。关于表格内容有一点务必注意单元格里的文字不要写太多。一个单元格超过三行表格就会变得臃肿阅读体验直线下降。如果确实需要大段描述把表格拆成两列或者在表格下方补一段补充说明。表格的美观还依赖内容的排序逻辑。经常看到有人把“重要程度”不同的内容混在一起顺序完全随缘。我的习惯是如果表格表达的是多个方案的对比就让列顺序保持“方案名称、关键参数、优劣比较、适用场景”这样的递进如果是数据罗列就按时间、数值大小、优先级排序。排序看似不起眼却是读者理解表格的第一线索。4.2 数学公式与脚注长文档的加分项如果你经常记理工科笔记数学公式几乎是绕不开的。基于 LaTeX 语法渲染公式的功能在很多编辑器中已经普及效果相当专业。行内公式用$...$包裹比如 $E mc^2$独立成行的公式用$$...$$包裹$$ \int_0^1 x^2 dx \frac{1}{3} $$公式的美观点在两个地方一是公式与正文之间留出空行让块级公式不完全嵌入段落文字二是公式中统一使用标准的数学变量斜体风格不要混用中文与公式符号。脚注是我个人非常喜欢的功能它能把补充说明和引用来源从正文中优雅地剥离出来。语法也不复杂在正文里写上内容[^1]。 [^1]: 补充解释或者出处的说明。脚注用好了整篇笔记的正文会更干净那些“这话怎么说”“哪来的数据”之类的旁逸内容都有了合适的去处。尤其是长文档脚注几乎是从好看到专业的必经之路。5. 进阶美化HTML 兜底、分隔线与折叠块5.1 什么时候需要用 HTML 兜底标准 Markdown 语法能覆盖绝大多数场景但有几个情况它处理不了比如精准控制图片尺寸、内容居中、设置颜色、调整行间距等。这时候就得让 HTML 标签兜底。Markdown 本身允许内嵌 HTML所以你可以直接写出这样的居中段落div styletext-align:center b这段话会居中显示/b /divcenter老式写法在部分平台兼容性差不建议使用/center居中、原色文字、自定义字号这些 HTML 标签虽然强大但有两个副作用一是降低了源代码的可移植性换到不支持内联样式的平台效果会失效二是破坏视觉纯净度科技笔记如果大量出现彩色文字和特殊居中整体风格容易走偏。我的原则是能用标准 Markdown 语法解决的场景绝不用 HTML只有图片尺寸、极少量的居中对齐、特殊字体这几个非用它不可的场景才考虑。而且尽量通过编辑器的“自定义样式”或主题统一处理而不是在每一篇文章里手写一堆style字符串。5.2 分隔线少即是多分隔线是一把双刃剑。适度使用能帮助读者感知章节之间的停顿特殊主题下还能充当审美符号但用得太多整页全是横向线条非常廉价。我一般只在以下情况使用分隔线正文中两个大主题切换、从说明区进入代码案例区、文档开头进入正文。规则是全文最多不超过三到五条。段落内部需要分隔时优先考虑用标题层级或列表结构表达而不是画一条线强行切分。还有一种情况是文档内部的锚点跳转现在不少编辑器支持生成目录但也有人喜欢在文章内写“点击跳转”。这种场景用标准 Markdown 的链接语法即可[跳转到第 3 节](#3-进阶美化html兜底分隔线与折叠块)注意标题转成锚点时一般遵循“去空格、大写转小写、去掉标点”规则不同平台略有差异最好实测确认。5.3 折叠块把信息藏得恰到好处折叠块是进阶排版里性价比很高的一项技能尤其适合“答案”型内容。你可以在笔记里先抛出问题让读者思考然后提供一个折叠区域点击展开就能看到参考实现和详细说明。标准 Markdown 不直接支持折叠但绝大多数现代笔记类编辑器都兼容 HTML 的details和summary标签写法也比较简单details summary点击查看参考答案/summary 这里是折叠的内容可以是文字、列表甚至代码块。 /details用折叠块的好处非常明显它让文档的信息密度可控。读者根据自己的需求决定展开哪些内容页面不会一开始就显得拥挤不堪。我的使用场景包括题目的详细解答、长代码段、额外参考资料的列表、不太重要但偶尔需要查看的历史说明。折叠块虽然好用也别滥用。如果一个页面里有七八个折叠块视觉上全是框框反而显得零碎。我建议一篇笔记最多安排三到五个确保百分之八十的内容在默认状态下是直接可见的否则读者会失去阅读耐心。6. 不同编辑器下的“同文不同颜”兼容性与书写习惯6.1 主流编辑器的渲染差异对照很多人在某个编辑器里排得特别舒服换到另一个平台就全线崩溃。这不是你的操作问题而是 Markdown 生态的天然现状。为了帮你减少意外我整理了一份常见差异对照表渲染能力本地编辑器在线文档平台代码托管平台标准 Markdown 语法支持支持支持上下标扩展不一致多数支持部分支持表格进阶功能合并单元格等多数不支持视平台而定多数不支持数学公式多数支持部分支持支持HTML 内嵌支持部分允许支持有限脚注多数编辑器支持部分支持部分支持从表格能看出来真正稳定可靠的其实是标准语法。扩展语法虽然能带来额外表现力但也意味着兼容性风险。6.2 换行规则两个空格与一个空行的战争换行是 Markdown 使用中最容易让人困惑的点也直接决定成品排版是否整齐。标准 Markdown 的硬换行要求行尾加两个空格再按回车才能看到换行效果。但大多数现代笔记编辑器已经做了折中处理直接按一次回车也能换行而在某些严格渲染环境里回车键造成的只是段内软换行视觉上仍跟上一行连在一起。我之前在同一份文档里混用了两种习惯导致在某个平台上有一段文字挤成了一整行。排查了半天才意识到是换行规则不同。后来我给自己的统一方案是段落之间一律用空行分隔即写完一段后按两次回车段落内部的强制换行尽量少用遇到需要列举多个短句时直接改用列表或引用块来组织。还有一个相关细节不要用多个连续的空行来制造“留白”。Markdown 连续空行会折叠成一个而且在不同平台表现不同用多空行制造间距的做法基本是白费力气。真想控制段间距应该在编辑器自带的样式或主题里设置而不是在内容里敲回车。6.3 我的兼容策略建立一份个人排版规范经历了不同平台间的格式翻车之后我现在形成了一套自己的排版规范。这套规范的所有条款都基于一个核心只用标准语法 少量必需的 HTML 兜底保证大概率兼容。具体来说我的规范是这样标题层级严格执行一级到三级不出现更深层级强调标记每段不超过三处加粗和斜体不同时使用引用块控制在三行内用途明确为提示或旁白列表最多两层固定使用-做无序列表标记图片都设置合理宽度并配有图注说明代码块一定标注语言行内代码只用于真正的代码术语表格中对齐方式与内容排序在做完表格后单独检查一遍文档末尾统一附参考链接区块正文中不出现裸链接数学公式只在使用它确实提升表达效率的场景下使用折叠块不超过五个且绝大多数内容默认可见在建这套规范之前我每次写完笔记都要花不少时间在细节调整上。建完之后排版时间大幅度缩短成品稳定度也明显上升。遇到特殊情况我会先把特殊写法在目标平台上快速测试一遍再决定是否纳入正文。结尾最后分享一个我实测很管用的小技巧每写完一篇笔记花两分钟只看“目录大纲”和“代码块列表”把页面滚一遍模拟读者扫读的节奏。如果这期间你看到了任何让你皱眉的地方——标题层级乱了、某段加粗太扎眼、图片大小不一致、表格挤成一团——立刻修正不要拖。这个方法把排版问题从“整体感觉”变成“具体节点”效率极高。当然Markdown 美观的标准永远会随着工具和审美变化所以不必追求一次到位。把上面这些常用技巧沉淀成自己的默认习惯你的每一篇笔记都会有一个稳定的底线然后在这个底线之上慢慢形成个人风格。真正实用的方案永远是自己用着顺手、读者读着舒服的那一套。