写 Markdown 的人迟早会撞上一堵墙想让某句话标红、想让一行标题大一号、想给一段提醒加个底色翻遍语法手册却发现 —— 纯 Markdown 里压根没有这些开关。我最初也以为是自己记漏了语法后来才想明白Markdown 的设计初衷就是专注内容、把排版交出去它天生不负责视觉细节。于是就有了 Markdown 内嵌 HTML 这条路用 HTML 标签和style内联样式在 Markdown 文档里直接控制字体颜色、字号、背景颜色既保留 Markdown 的书写效率又拿到精确的视觉控制权。这份笔记记录的就是我在实际写文档、做技术方案、整理知识库时关于Markdown 内嵌 HTML 改颜色改字号这一套的完整沉淀哪些写法真的能渲染出来哪些平台会把样式吃掉块级 HTML 和 Markdown 语法怎么互相打架以及导成 PDF、Word、公众号图文时样式还剩多少。内容偏向实操适合三类人看一是刚接触 Markdown、想给自己笔记加重点的初学者二是被不同渲染器兼容性折磨过的文档维护者三是需要输出交付文档、技术方案、对外图文的从业者。下面按为什么用、怎么写、怎么坑里爬出来的顺序展开。1. 先搞清楚 Markdown 的能力边界再决定要不要内嵌 HTML很多人上手第一反应是我要用颜色但真正该先问的是我这套文档最终在哪儿被渲染。因为内嵌 HTML 的所有麻烦本质上都来自同一件事Markdown 渲染器不是一个统一标准而是一堆实现各异的解析器加安全过滤器。1.1 纯 Markdown 能表达什么表达不了什么纯 Markdown 的排版能力用一句话概括就是语义层级 少量行内强调。它能做的是标题分级、有序无序列表、引用块、代码块与行内代码、链接图片、表格、加粗斜体删除线、分割线。这些足够写出一篇结构清晰的技术文也足够让人快速读完。但它的短板同样明确。第一是没有颜色无论是文字色还是背景色都无从谈起第二是没有字号控制#到######只解决层级不解决这一行我要 20px的需求第三是没有对齐控制表格可以对齐正文段落不行第四是没有容器的视觉区分你只能用引用块模拟提示框所有平台的引用块长得还都不一样。这四条短板里前两条恰好是本文主题的核心。所以结论很清楚只要你对文档的视觉表达有超出层级清晰的要求Markdown 本身就不足以承载必须借助外部手段。而 HTML 是成本最低的那条路因为 Markdown 从诞生起就允许内嵌 HTML —— 原始设计里就写着Markdown 是 HTML 的子集你随时可以退回 HTML。1.2 什么场景值得内嵌 HTML什么场景该忍住我的判断标准很粗暴看这份文档是长期维护还是一次性输出。长期维护的文档 —— 比如知识库笔记、项目 README、团队规范 —— 我倾向于尽量少用内嵌 HTML。原因不是它不好用而是维护成本会爆炸。你半年后回来改内容看到span stylecolor:#d93025;background:#fce8e6;padding:2px 6px;border-radius:3px这一长串第一反应是这啥。更麻烦的是团队协作别人用别的编辑器打开样式可能直接变成一堆乱码似的标签。而一次性输出或对外交付的文档—— 发布会材料草稿、交付说明、要贴进富文本编辑器的图文、发给客户看的方案 —— 内嵌 HTML 的价值就很大。因为它的样式是跟随内容走的复制粘贴到支持 HTML 的地方颜色和底色会一起被带过去这是纯 Markdown 做不到的。还有一个容易被忽略的场景自用笔记的视觉分层。我自己的复盘笔记里红色代表踩过的坑黄色底代表待验证绿色代表已验证可行。这套颜色体系帮我省了大量重新阅读的时间因为眼睛扫过去就知道哪段值得细看。这种自用场景下兼容性风险为零只有我自己看收益却很高。提示如果你所在团队用统一的文档平台先在平台上试一次最小样例确认样式没被过滤再决定要不要批量改。不要写完三十页才发现颜色上不去。1.3 内嵌 HTML 的三种存活状态决定了你的写法选择我把内嵌 HTML 在不同环境里的命运归纳成三种状态这个模型帮我省了很多试错时间。存活状态表现典型环境特征完整渲染标签和样式都生效所见即所得本地编辑器、自建渲染、桌面端笔记软件标签保留、样式剥离文字还在颜色字号全没了代码托管平台的 README 渲染整体转义或删除标签原样显示成文本或整段消失部分在线文档平台、富文本编辑器粘贴第一种状态下你可以放心用spanstyle。第二种状态下用样式是白费功夫不如回归 Markdown 本身的引用块和加粗。第三种状态最坑因为它是看起来能用 —— 编辑时预览正常发布后变成一堆尖括号读者一脸问号。搞清这三种状态之后写法的选择就变得很理性了优先使用语法简单、属性少的写法因为越简单越容易被过滤器放行。这也是我在下一节要推荐的方案背后的真正原因 —— 不是span style比font高级而是它在更多环境里能活下来。2. 字体颜色、字号、背景色的最小可用写法先给结论行内文字改色改字号优先用span style...需要兜底时补一个font color。这两个写法覆盖了我 95% 以上的实际需求。下面把细节讲透。2.1 font 标签能用但不该当主力font是最古老的写法语法极简font color#d93025这段文字是红色的/font font size5这段文字字号大一点/font它的优点是兼容面广很多渲染器对它有专门放行因为实现简单、没有复杂属性。缺点是能力太窄color只能管前景色size只能填 1 到 7 的档位不是像素是相对档位没法设背景色也没法设粗体之外的字重、间距、圆角。更关键的一点font在现代网页标准里已经属于废弃标签浏览器虽然还支持但新版本渲染器随时可能把它从白名单里拿掉。所以我现在的用法是能用span style就用span stylefont只作为兜底备选。所谓兜底是指某些环境里style属性被剥离了、但color属性还能过的时候你可以两句一起写。2.2 span style当前最通用的方案完整写法长这样span stylecolor:#d93025;红色文字/span span stylecolor:#d93025; background-color:#fce8e6; padding:2px 6px; border-radius:3px;带底色的红色标签/span span stylefont-size:20px;字号放大到 20px/span三个属性各司其职color管文字颜色background-color管背景色font-size管字号。额外两个是锦上添花padding让底色不贴字border-radius给底色加圆角视觉上更像一个标签而不是一块硬邦邦的色块。这里有个新手最容易踩的细节padding和background-color在行内元素上的表现是有条件的。span默认是display:inline垂直方向的padding不会撑开行高表现出来就是背景色上下被压扁了。如果你追求四周都均匀留白可以加display:inline-blockspan styledisplay:inline-block; color:#fff; background-color:#d93025; padding:3px 10px; border-radius:4px;发布/span加上inline-block之后垂直方向的 padding 才真正生效色块四边留白一致。代价是它可能影响行内换行行为 —— 如果这个标签出现在一段长文字中间加上inline-block后它整体不会被拆到两行可能把行撑得有点松。这两种写法我都用看场景切换。2.3 常用内联样式属性速查表下面这张表是我实际用得最多的属性集合按使用频率排序。你可以把它当成一个临时查表不用背。属性作用常用取值示例备注color文字颜色#d93025、rgb(217,48,37)、red最常用background-color背景色#fce8e6、rgba(255,0,0,0.1)需要 padding 配合才好看font-size字号14px、1.2em、120%px 最直观font-weight字重600、bold比b更可控padding内边距2px 6px行内元素垂直方向需 inline-blockborder-radius圆角3px、999px999px 出胶囊形border边框1px solid #d93025做描边标签text-align水平对齐center、right只对块级元素有效font-family字体monospace、serif常用于代码风格文字letter-spacing字距1px小标题加疏排这张表之外还有两个小提醒。一是单位问题font-size用px最稳定用em会继承父级字号在层级嵌套的 HTML 块里容易算错%同理。二是简写属性慎用像font: 14px/1.5 sans-serif这种简写形式某些过滤器解析不完整可能整条被丢掉不如拆成三个属性写。2.4 颜色的四种取值方式以及我为什么常驻十六进制CSS 支持的颜色写法有好几种在 Markdown 内嵌 HTML 里都能用span stylecolor:red;命名色/span span stylecolor:#d93025;十六进制/span span stylecolor:rgb(217,48,37);RGB/span span stylecolor:hsl(3,71%,50%);HSL/span span stylecolor:rgba(217,48,37,0.5);带透明度的 RGBA/span我现在的习惯是十六进制为主RGBA 为辅。原因很实际十六进制最紧凑写起来短复制到任何工具都不会被解析歧义而命名色虽然写着省事但到底这个 red 是哪种红完全由渲染器决定同一条笔记在不同平台可能深浅不一。至于 HSL可读性确实好色相、饱和度、亮度一目了然但我记不住自己常用色的 HSL 值每次都要转换反而低效。RGBA 的用途比较特殊主要用来做半透明底色。比如你要在一个已经有底色的区域里再叠一层浅色标记用rgba(255,193,7,0.25)这种半透明黄叠上去之后下层的文字依然能看清不会因为色块过实而糊掉。这个技巧在给表格行做隔行变色时特别有用。注意如果同一个色块要出现在深浅两种主题下比如白天模式和夜间模式用纯色十六进制很容易在深色背景上消失。这种情况下要么单独为深色主题写一份样式要么老老实实用半透明色 描边组合靠色彩对比度而不是底色本身来区分。颜色的选择上还有个经验一篇文章里不要超过三种强调色。我见过不少人一开始玩得开心红黄蓝绿紫全上最后文档看起来像调色盘打翻了。我自己的规则是红重要/风险、黄待办/注意、绿已完成/推荐三色足够其他情况一律用加粗和引用块解决。3. 进阶玩法提示卡片、表格、图片布局与折叠块行内改色只是入门真正让 Markdown 文档看起来像出版物的是块级元素的使用。这部分我按投入产出比从高到低排。3.1 用 div 拼一个提示卡片最实用的块级写法是提示卡片。语法本身不复杂div stylebackground-color:#fff8e1; border-left:4px solid #f9a825; padding:12px 16px; margin:12px 0; border-radius:0 4px 4px 0; **这里是标题**下面是内容…… /div这段的重点不在样式本身而在两个布局细节。第一是border-left配一个浅底色视觉上形成侧边强调条比四周都有边框的方框更轻盈也更符合现在常见的文档设计语言。第二是border-radius只给右侧加圆角写成0 4px 4px 0顺序是左上、右上、右下、左下左侧保持直角和那条竖线对齐看起来更利落。但这里出现了一个必须提前讲清楚的坑块级 HTML 内部的 Markdown 语法默认不会被解析。上面那个**这里是标题**在某些渲染器里会原样显示成带星号的文本。这是 CommonMark 规范的明确规定 —— 块级 HTML 标签内部的文字被视为原始 HTML 内容不再走 Markdown 解析流程。解决方式有三种按可靠性排序一是内部直接改用 HTML 标签strong代替**二是在支持markdown属性的解析器里加markdown1三是干脆把卡片做成外壳 内部单独成段的结构也就是让内容脱离 HTML 块的包裹。第三种最省心但做不到严丝合缝的视觉包裹。3.2 表格单元格里塞样式Markdown 表格的单元格里是可以放行内 HTML 的这个特性用来做状态标记特别顺手| 模块 | 状态 | 负责人 | | --- | --- | --- | | 数据接入 | span stylecolor:#188038;已完成/span | 张三 | | 报表导出 | span stylecolor:#f9a825;进行中/span | 李四 | | 权限体系 | span stylecolor:#d93025;未开始/span | 王五 |三个字的状态用颜色区分比写已完成/进行中/未开始再让人读一遍更高效。表格里用 HTML 有两个必须注意的点。第一是管道符冲突|是表格的列分隔符如果你的样式值里出现了|必须转义成\|否则整张表会被拆乱。第二是换行问题单元格里不能直接写br之外的多行内容想在单元格里换行只能用br直接回车会把表格结构打断。还有个更隐蔽的坑部分渲染器会先按|切分单元格再解析单元格内容所以哪怕你的 HTML 标签是完整闭合的只要它跨越了|的位置就会被切碎。判断方法很简单 —— 写完预览一次看看标签有没有原样漏出来。3.3 图片尺寸、居中与并排Markdown 原生的图片语法没法控制尺寸只能给原图。想控制大小必须改用 HTMLimg src./images/arch.png width480 alt架构图width和height是最容易被渲染器放行的属性比stylewidth:480px的存活率高得多。只写width让高度自动等比缩放是最省事也最不容易变形的做法。居中的写法是包一层带align属性的块元素p aligncenter img src./images/logo.png width200 altLogo /p这里用aligncenter而不是styletext-align:center同样是出于兼容性考虑 —— 属性比样式更容易被放行。实测这个写法在多数文档平台和代码托管平台的 README 里都能正常居中。并排两张图的做法是包一个表格Markdown 表格或 HTML 表格都行每张图放一格借助表格天然的分列能力实现并排。但要注意表格会强制等宽分列两张图尺寸差异很大的时候小图会被拉到和大图一样宽的格子里显得很空。想让两张图并排且宽度按内容分配就得回到 HTML 表格并显式指定宽度复杂度会上升。我的建议是除非是明确的前后对比场景否则不要把图并排竖着排反而更好读。3.4 用 details 做折叠内容details和summary是 HTML 里自带的折叠控件在很多文档环境里都能正常展开收起details summary点击展开完整的参数配置表/summary | 参数 | 默认值 | 说明 | | --- | --- | --- | | timeout | 30 | 超时秒数 | | retry | 3 | 重试次数 | /details用它的最大好处是长内容可以收起来但搜索和复制依然能找到。相比截图或者外链它对读者更友好。这里的关键细节是summary后面和/details前面都留一个空行否则内部的 Markdown 表格可能不会被解析直接显示成一堆竖线。折叠块特别适合放三类内容大段日志或代码、完整参数表、可选的背景知识。这三类内容的共同点是读的人需要时才看把它们折叠起来能显著缩短文档的视觉长度让主线更清楚。提示折叠块不要嵌套太多层。两层已经很难用了三层以上读者基本不会去展开等于白写。需要多层结构的时候考虑拆成独立章节。4. 语法陷阱空行、缩进与 Markdown 解析的相互干扰前面反复提到空行和解析这一节专门讲它们。因为我在这一块浪费的时间比在样式本身花的时间多得多。4.1 块级 HTML 前后必须留空行这是最高频的坑没有之一。规则是块级 HTML 标签div、table、p 等要想被当作独立的块处理它前面和后面都必须有空行而且它不能有缩进。这一段是普通文字。 div stylepadding:8px; background:#f5f5f5;这是一个灰底块/div 这一段是另一段普通文字。如果写成没有空行的形式这一段是普通文字。 div stylepadding:8px; background:#f5f5f5;这是一个灰底块/div 这一段是另一段普通文字。那么整个结构会被当成一个段落标签可能被当作段内原始 HTML 处理也可能直接转义显示。不同渲染器的处理结果还不一样有的正常有的乱非常难排查。我现在的习惯是凡是要写块级 HTML前后各敲一个空行标签顶格写绝不缩进。这三条记住了绝大多数解析异常都能避免。4.2 缩进四格会被当成代码块第二高频的坑。Markdown 里四个空格或一个制表符的缩进表示代码块。如果你为了让 HTML 层次好看而给标签加了缩进那一整段就会被渲染成代码块 —— 显示出来的是一堆原样的标签文字样式完全无效。这个问题在嵌套结构里特别容易犯比如把div里的内容缩进一层div stylepadding:8px; background:#f5f5f5; 这行缩进了四个空格会被当成代码块 /div解决办法是内层内容不缩进靠空行分隔。虽然从代码美观角度看不爽但在 Markdown 里这是必须接受的现实。4.3 换行的四种写法与各自代价换行看起来是小事实际上在HTML Markdown 混合的文档里经常出问题。下面是我常用的四种方式写法效果注意事项行尾两个空格 回车软换行多数编辑器保存时会自动删除行尾空格行尾反斜杠 回车硬换行部分渲染器不支持br强制换行最通用推荐空一行新起段落段落间距由样式决定不是换行我的实际选择是优先用br。原因是行尾两个空格这个写法太脆弱了 —— 你在编辑器里设了保存时删除行尾空白很多团队默认开这个保存一次空格就没了换行效果消失而你还不知道为什么昨天好好的今天就不换行了。这个坑我踩过至少三次。还有一个隐蔽问题块级 HTML 块内部的换行会被当作空白折叠。也就是你在div里写三行文字渲染出来可能拼成一整段。想真换行还是得用br想真分段就得出 HTML 块再重新进入。这是 HTML 本身的渲染规则不是 Markdown 的问题但在混合文档里经常让人困惑。5. 各环境实测对比与导出存活率这一节的内容会随版本变化我给的是我自己在用的那一批环境下的观察结果你在自己的环境里最好用一段最小样例先验证一次。5.1 渲染环境对照表环境类型行内 style块级 div备注桌面端本地编辑器通常生效通常生效渲染能力强所见即所得代码托管平台 README通常被剥离标签保留文字还在颜色没了在线协作文档平台视平台而定部分保留有的直接转义成文本本地笔记软件生效生效但导出时行为不一致富文本编辑器粘贴部分保留部分保留样式常被简化这张表里最需要留意的两行是README和在线协作文档平台。前者会保留标签、剥掉样式结果就是你的颜色全丢但排版还在看起来不丑但完全没达到目的后者最不可预测同一个平台不同页面类型的处理规则都可能不一样。我的应对策略是双轨制凡是需要发布到高过滤环境的文档正文一律用纯 Markdown 组织视觉强调靠加粗、引用块和列表只在明确知道自己要往哪儿发的场景下才附加 HTML 样式。这样即使样式全丢文档的可读性也不会崩。5.2 导出场景样式能活下来多少导出比在线渲染更复杂因为多了转换器这一层。导成 HTML 是最理想的因为 Markdown 转 HTML 本质是转义样式天然保留。导成 PDF 分两种情况走 HTML 渲染引擎的先转 HTML 再转 PDF样式基本能保留走排版引擎的转成中间格式再排版内联样式基本会被丢弃只保留结构。导成 Word 是丢样式最严重的因为 Word 用的是自己的样式体系HTML 的内联样式要么被忽略要么被转换成不伦不类的直接格式。我踩过最典型的一次坑是给客户交付的说明文档里有大量彩色状态标记我写的时候预览一切正常导出成 Word 之后全部变成黑字客户还问我你说的红色标记在哪儿。后来我的做法是改成文字 符号双重表达比如待确认注意、已完成确认颜色只是锦上添花而不是唯一信息载体。这个原则现在我一直坚持颜色永远不能是唯一的信息通道因为它随时可能在某个环节消失。如果确实需要导出带样式的文档可行路径是先用 Markdown 生成 HTML再从 HTML 导出目标格式或者直接交付 HTML 文件。多一步转换样式存活率会高不少。注意涉及到对外正式交付的场景建议在最终交付前用目标格式打开检查一遍而不是相信预览效果。预览和导出走的经常不是同一条渲染链路。5.3 那些看起来能用其实不能用的情况最后列几个容易被误判的情况都是我在实际使用中发现的。第一种是编辑器预览专用样式。有些编辑器会在自己的预览窗口里额外注入一套样式让你的 HTML 看起来效果很好但这套样式是编辑器加的不是文档自带的。换个环境打开效果立刻不同。判断方法把同一段内容复制到另一个环境里对比。第二种是主题适配导致的失效。很多编辑器和平台支持深浅主题切换你用浅色背景配合深色文字写的卡片在深色主题下可能变成深底深字完全看不见。这不是样式没生效而是生效了但不合适。我在写带底色的内容时会刻意保证前后对比度足够或者干脆用描边代替填充底色。第三种是复制粘贴时的样式衰减。从 Markdown 预览区复制到富文本编辑器第一次粘贴颜色还在再复制一次就没了因为中间经过了纯文本剪贴板。想保住样式尽量一次性从源头复制到目标位置中间不要经过记事本之类的纯文本工具。6. 问题排查速查表与实操心得6.1 症状对照速查表症状大概率原因处理方式标签原样显示成文本环境整体转义 HTML换写法或放弃样式文字正常但颜色没了style 属性被剥离改用平台支持的强调方式样式完全无效但没报错标签前缺空行被当成段落内容前后各加一个空行标签顶格整块变成代码标签有四个空格缩进取消缩进卡片里的加粗不生效块级 HTML 内不解析 Markdown内部改用 HTML 标签底色上下被压扁行内元素垂直 padding 不生效加 display:inline-block表格被拆乱样式值里有未转义的竖线竖线写成反斜杠加竖线换行昨天好今天没了行尾空格被编辑器自动删除改用 br 标签这张表覆盖了我遇到过的绝大多数问题。实际排查的时候我的顺序是先看标签是不是原样显示判断是否被整体转义再看文字在不在判断是剥样式还是删内容最后看空行和缩进判断是不是解析问题。按这个顺序走基本三分钟内能定位。6.2 三个我反复用到的实操心得第一个心得先写一段最小样例再去写正文。每次我换到一个新平台或是新编辑器第一件事是新建一个空文档写三行一行红色文字、一行带底色的文字、一个带样式的块。预览一次就知道这个环境能吃多少。这个动作花三十秒能省掉后面几十分钟的返工。第二个心得颜色用变量思维管理别随手挑。我现在固定用一套三色红色表示风险或重点黄色表示待验证绿色表示已完成。所有文档共用这一套好处是跨文档一致性高我自己看到颜色就能立刻判断语义不用回想这个橙色当时是什么意思。颜色一多语义就崩了。第三个心得给样式留退路。每处用颜色的地方我都保证去掉颜色之后信息依然完整。比如未开始三个字本身就有语义颜色只是加速识别。这样即使某个环境把颜色全吃了文档也不至于变成一堆无意义的色块。这一条我认为是整篇笔记里最值得带走的经验 —— 它把样式和信息彻底解耦了。提示如果你在维护团队共用的文档模板建议把常用样式片段集中放在一个附录页里需要用的时候复制粘贴。这比每个人各自发明一套写法要好得多后续统一调整也方便。最后分享一个我最近才养成的习惯把常用的几个样式片段存成代码片段或者文本模板用的时候直接调用不手写。因为这个东西写多了之后很容易在引号、分号、括号上出小错而这类错误的表现往往只是样式没生效没有任何报错提示排查起来特别费时间。有个现成的片段兜底出错概率会低很多。这套东西本质上不复杂真正花时间的从来不是学会写法而是搞清每个环境愿意接受什么、以及怎么让内容在样式丢失的情况下依然站得住。