这篇写给「文章里贴了代码、读者却看不清关键字」的人:问题不是内容不够,而是 Markdown 渲染器(把 Markdown 文本转成页面元素的组件)把代码块当普通文本输出了。读完你能带走一段二十多行的代码块组件、按需注册语言(只引入真正用到的语言)的体积账,以及三个不用截图也能验证高亮生效的信号(其中两个可以自动判)。
下面这张表格按角色列出你能带走什么、从哪节开始读。
| 读者 | 带走什么 | 拿它做什么 | 从哪节开始读 |
|---|---|---|---|
| 用 Markdown 写技术文章的人 | 代码块高亮的接入方法 | 照第 4 节替换渲染器的 code 组件 |
2 → 4 |
| 在意首屏体积的前端 | 全量与按需的体积对比 | 用第 3 节的方法量自己的包 | 3 |
| 做验收的人 | 两个可自动化的判据 + 一个肉眼确认项 | 抄第 7 节的类名与 span 数检查 | 7 |
不适合不使用 Markdown 的内容站。约 11 分钟读完;需要你会一点 React、知道 Markdown 会转成 HTML;没配过语法高亮也能跟。
Markdown 里的代码块,最终会变成一个 <pre><code> 元素。这个元素里有没有被拆开上色的片段,取决于渲染器有没有接语法高亮。这篇按「先看现象 → 再量体积 → 再接组件 → 最后验收」的顺序讲清整条链路。
下面这张表格是全文路线。
| 小节 | 讲什么 | 解决什么问题 |
|---|---|---|
| 1 | 为什么代码块是黑白的 | 找到缺的是哪一环 |
| 2 | 环境准备与最小示例 | 先看到高亮后的 HTML 长什么样 |
| 3 | 全量加载与按需加载 | 决定注册多少语言、怎么量体积 |
| 4 | 接到渲染器的代码块组件 | 让页面真的用上高亮 |
| 5 | 别名与未知语言 | 文章里写 ts、sh 也能对上 |
| 6 | 样式作用域与配色 | 让颜色只影响文章正文 |
| 7 | 三个验收信号 | 不用截图判断有没有生效 |
| 8 | 边界与演进 | 知道现在做不到什么 |
Markdown 渲染器是「把 Markdown 文本转成页面元素」的那层组件,它通常允许你按标签替换默认输出,例如换掉图片、链接、标题的渲染方式。这个站点之前只替换了图片组件(给图片加 referrerPolicy,处理图床防盗链),代码块没替换,于是 <pre><code> 按默认方式输出:类名还在(language-js 之类),但没有程序去读它,没有额外标签,也没有配色。
结构上的差别看下面这段示意。上面是修复前的输出,下面是高亮之后的输出,标签 <span> 是新增的。
修复前:
<pre><code class="language-js">const n = 42;</code></pre>
修复后:
<pre><code class="hljs language-javascript">
<span class="hljs-keyword">const</span> n = <span class="hljs-number">42</span>;
</code></pre>
所以缺的不是 CSS,而是一个「读类名 → 切词 → 给每段包标签」的步骤。token 指被单独上色的一段,例如关键字、字符串、注释、数字各算一个 token。
这一节先确认「高亮」到底产出什么,避免后面接组件时靠猜。环境是 Node.js 18 以上,装一个语法高亮库:npm i highlight.js@^11.12.0。示例代码如下,它会打印高亮后的 HTML 字符串与 <span> 个数。
const hljs = require('highlight.js/lib/core');
hljs.registerLanguage('javascript', require('highlight.js/lib/languages/javascript'));
const out = hljs.highlight('const n = 42;', { language: 'javascript' }).value;
console.log(out);
console.log('span 数:', (out.match(/<span/g) || []).length);
运行 node hl.js(保存成 .js,这个示例用的是 CommonJS 的 require),会看到 const 被包成 hljs-keyword、42 被包成 hljs-number,span 数为 2。注意入口是 lib/core:它只有框架,不含任何语言,所以每个要用的语言都必须单独引入并注册——漏了注册,高亮函数会找不到这门语言。
这一节解决体积问题。highlight.js 支持两种用法:引入完整包,或从 lib/core 起按需注册。完整包包含近两百种语言,打包后量级约 1MB(是否压缩、压到多少取决于构建配置);按需只加你真正用到的语言,每种通常几 KB。本站注册 11 种后是几十 KB 量级。这两个数都用你的打包产物核对,别照抄——版本和压缩方式一换,数字就不一样。下面这张表格对比两种加载方式。
| 方式 | 包含语言 | 体积量级 | 适合 |
|---|---|---|---|
| 完整包 | 近 200 种 | 约 1MB | 站点语言不固定、不在乎首屏 |
| 按需注册 | 你自己列的清单 | 每种几 KB | 内容语言可枚举的博客、文档站 |
本站按需注册了 11 种语言。这个数字是数出来的,不是猜的:把所有文章的代码围栏语言收集一遍去重,就是清单。
# 列出文章里出现过的代码块语言(+ 表示至少一个字符,排除闭合围栏)
grep -rho '^```[a-zA-Z0-9-]\+' posts/ | sort -u
# 输出形如 ```js / ```bash
行内代码是单个反引号,不会匹配上面的正则;闭合围栏是单独的三个反引号,也已经用 + 排除。剩下的若有拼写错误,人工核对一遍,就是注册清单。语言种类增加时,按需加载的收益会变小,这时可以改成「每种语言单独拆包,按需下载」。
这一节解决「高亮函数写好了,页面没用上」的问题。渲染器会把块级代码包一层 <pre>,再把 className 传进来(通常形如 language-js);行内代码没有这个 language- 前缀。所以组件只返回 <code>,不要自己再包 <pre>,否则会嵌套出 <pre><pre>,把段落间距打乱。className 是 React 传给组件的类名参数;children 是代码文本。
示例代码如下,它接收类名与内容,返回带高亮标签的代码块。语言名用注册名输出(language-javascript),而不是文章里写的别名(language-js),这样样式和验收只需要认一套名字。
import hljs from 'highlight.js/lib/core';
import javascript from 'highlight.js/lib/languages/javascript';
import bash from 'highlight.js/lib/languages/bash';
import plaintext from 'highlight.js/lib/languages/plaintext';
// 其余语言同样 import 并注册;ALIASES 里出现的都要注册
hljs.registerLanguage('javascript', javascript);
hljs.registerLanguage('bash', bash);
hljs.registerLanguage('plaintext', plaintext);
const ALIASES = {
ts: 'typescript', js: 'javascript', node: 'javascript',
sh: 'bash', html: 'xml', yml: 'yaml', text: 'plaintext',
};
export default function CodeBlock({ className = '', children }) {
const lang = (className.match(/language-([\w-]+)/) || [])[1];
if (!lang) return <code>{children}</code>; // 行内代码
const target = ALIASES[lang] || lang;
if (!hljs.getLanguage(target)) {
// 未知语言降级成纯文本;外层的 <pre> 由渲染器提供
return <code className="hljs language-plaintext">{children}</code>;
}
const html = hljs.highlight(String(children).replace(/\n$/, ''), {
language: target,
}).value;
return (
<code
className={`hljs language-${target}`}
dangerouslySetInnerHTML={{ __html: html }}
/>
);
}
把组件交给渲染器的方式因库而异,但都是「按标签名替换」:
// 在渲染 Markdown 的地方(不同库的字段名可能不同)
<Markdown components={{ code: CodeBlock }}>
{content}
</Markdown>
两个细节:外层 <pre> 由渲染器提供,组件只返回 <code>,这样行内与块级都不会出现嵌套;dangerouslySetInnerHTML 在这里是必要的,因为高亮库返回的是 HTML 字符串,它只处理你仓库里的 Markdown,不要把它用在用户提交的内容上。
文章里写代码块时,语言名是人写的:ts、js、sh、yml 都很常见,而高亮库注册的是 typescript、javascript、bash、yaml。这一节把两套名字对上。下面这张表格是常见的别名对应关系。
| 文章里写的 | 注册的语言 | 说明 |
|---|---|---|
js / node |
javascript |
同一个语言,不同习惯 |
ts |
typescript |
需要先 import 并注册 |
sh |
bash |
注册名是 bash |
html |
xml |
标记语言共用一套规则 |
yml |
yaml |
少一个 a 的常见写法 |
text |
plaintext |
明确不配色,但仍走同一套类名 |
| 拼错的名字 | plaintext |
降级成纯文本,保留排版 |
降级这一行很重要:未知语言不能让构建失败,也不能让代码块消失,只保留渲染器的 <pre> 等宽排版。这样作者写错语言名时,文章仍然能读,只是没有颜色。
高亮只负责加类名,颜色要靠 CSS。这一节解决「颜色跑到导航栏去」的问题:把所有 token 样式限定在文章正文容器里,而不是全局。
hljs 输出的类名是稳定的(hljs-keyword、hljs-string、hljs-comment 等),下面这张表格是当前主题的四个主要颜色,调主题时用来对照,不是判据。
| 类名 | 含义 | 当前颜色 |
|---|---|---|
hljs-comment |
注释 | rgb(160, 161, 167) |
hljs-keyword |
关键字 | rgb(166, 38, 164) |
hljs-string |
字符串 | rgb(80, 161, 79) |
hljs-built_in |
内置对象/函数 | rgb(193, 132, 1) |
选择器统一写成 .markdown-content .hljs-keyword { … } 这种形式,只影响正文;背景色与内边距放在 pre code.hljs 上,避免每个 token 自己撑开间距。
改完之后怎么确认真的生效?不用截图,看三个信号就够,按从易到难排列。下面这张表格是三个信号与各自的取法。
| 信号 | 怎么取 | 期望 | 强度 |
|---|---|---|---|
| 外层类名 | 选中文章里的代码块,看 <code> 的 class |
同时有 hljs 和 language-<注册名> |
弱:只证明组件被调用 |
| 内部标签数 | 数 <code> 里 <span> 的个数 |
与语言有关,纯文本块为 0 | 中:证明切词真的跑了 |
| 计算样式 | 看某个 span 的 color |
不是继承的正文颜色 | 强:证明配色生效 |
实测数据可以做参照(取法:在浏览器开发者工具里选中 <code>,数其中 <span> 的数量):同一篇 bash 文章里的三个代码块分别是 16、5、14;一个 JavaScript 示例块是 62;标成 text 的块是 0。数量不用和这里一致,同一门语言、内容越长,切出来的 token 越多;要确认的是「不为 0 且随内容变化」。
类名这一项要特别注意:如果组件输出的还是 language-js 而不是 language-javascript,说明你用的是原始别名,样式表和验收脚本会各认一套名字,迟早对不上。
当前这套做法的边界很清楚:
<pre><code>,浏览器接管后才着色,首屏可能闪一下黑白。下一步可以往三个方向走:把高亮移到构建期,直接产出带标签的 HTML,消除闪烁;语言多了之后,把每种语言拆成独立文件按需下载,避免主包变大;把「语言清单」和「文章里实际出现的围栏语言」做成构建检查,出现未注册的语言时给出警告,而不是静默降级。
打开你文章页的一个代码块,数一下 <code> 里的 <span> 个数。如果是 0,说明高亮没接上;先照第 2 节在 Node 里跑通,再照第 4 节换渲染器的 code 组件。
这些内容来自一个静态博客渲染层的修改:文章里贴了大量命令与代码,读者反馈「看不出关键字」。排查发现渲染器只替换了图片组件,代码块走了默认输出。随后按站点实际出现的 11 种语言做按需注册,并用类名、标签数、计算样式三层验证。文中的 span 数量来自对已发布文章的实际统计,颜色值来自最终生效的样式表。
本站缺少完全同主题的文章,以下是改动范围最接近的几篇。