在这篇文章中,我们将探索如何使用 Expressive Code 来增强 Markdown 中的代码块显示。以下示例基于官方文档,您可以查阅文档以获取更多详细信息。
1. 语法高亮 (Syntax Highlighting)
Expressive Code 提供了强大的语法高亮功能。
常规语法高亮
console.log('这段代码具有语法高亮!')渲染 ANSI 转义序列
ANSI 颜色示例:- 标准: 红色 绿色 黄色 蓝色 洋红 青色- 加粗: 红色 绿色 黄色 蓝色 洋红 青色- 变暗: 红色 绿色 黄色 蓝色 洋红 青色
256 色 (显示 160-177):160 161 162 163 164 165166 167 168 169 170 171172 173 174 175 176 177
全 RGB 颜色:森林绿 - RGB(34, 139, 34)
文本格式: 加粗 变暗 斜体 下划线2. 编辑器与终端外框 (Editor & Terminal Frames)
代码编辑器外框
```js title="my-test-file.js"console.log('带有标题属性的示例')``````markdown
```js title="my-test-file.js"console.log('带有标题属性的示例')```markdown
---<div>通过注释指定文件名的示例</div>```<!-- src/content/index.html --><div>通过注释指定文件名的示例</div>终端外框
```bashecho "这个终端外框没有标题"``````markdown
```bashecho "这个终端外框没有标题"```markdown
---Write-Output "这个带有一个标题!"```Write-Output "这个带有一个标题!"覆盖外框类型
```sh frame="none"echo "看,没有任何外框!"``````markdown
```sh frame="none"echo "看,没有任何外框!"```markdown
---# 如果不手动覆盖,这通常会被自动识别为终端外框function Watch-Tail { Get-Content -Tail 20 -Wait $args }New-Alias tail Watch-Tail```# 如果不手动覆盖,这通常会被自动识别为终端外框function Watch-Tail { Get-Content -Tail 20 -Wait $args }New-Alias tail Watch-Tail3. 文本与行标记 (Text & Line Markers)
标记整行或行范围
```js {1, 4, 7-8}// 第 1 行 - 通过行号标记// 第 2 行// 第 3 行// 第 4 行 - 通过行号标记// 第 5 行// 第 6 行// 第 7 行 - 通过范围 "7-8" 标记// 第 8 行 - 通过范围 "7-8" 标记``````markdown
```js {1, 4, 7-8}// 第 1 行 - 通过行号标记// 第 2 行// 第 3 行// 第 4 行 - 通过行号标记// 第 5 行// 第 6 行// 第 7 行 - 通过范围 "7-8" 标记// 第 8 行 - 通过范围 "7-8" 标记```markdown
#### 选择行标记类型 (mark, ins, del)function demo() { console.log('这一行被标记为已删除') // 这一行和下一行被标记为已插入 console.log('这是第二个插入行')
return '这一行使用中性的默认标记类型'}```function demo() { console.log('这一行被标记为已删除') // 这一行和下一行被标记为已插入 console.log('这是第二个插入行')
return '这一行使用中性的默认标记类型'}为行标记添加标签
```jsx {"1":5} del={"2":7-8} ins={"3":10-12}// labeled-line-markers.jsx<button role="button" {...props} value={value} className={buttonClassName} disabled={disabled} active={active}> {children && !active && (typeof children === 'string' ? <span>{children}</span> : children)}</button>``````markdown
```jsx {"1":5} del={"2":7-8} ins={"3":10-12}// labeled-line-markers.jsx<button role="button" {...props} value={value} className={buttonClassName} disabled={disabled} active={active}> {children && !active && (typeof children === 'string' ? <span>{children}</span> : children)}</button>```markdown
#### 添加长标签// labeled-line-markers.jsx<button role="button" {...props}
value={value} className={buttonClassName}
disabled={disabled} active={active}>
{children && !active && (typeof children === 'string' ? <span>{children}</span> : children)}</button>```// labeled-line-markers.jsx<button role="button" {...props}
value={value} className={buttonClassName}
disabled={disabled} active={active}>
{children && !active && (typeof children === 'string' ? <span>{children}</span> : children)}</button>使用类似 Diff 的语法
```diff+这一行将被标记为已插入-这一行将被标记为已删除这是一行普通代码``````markdown
```diff+这一行将被标记为已插入-这一行将被标记为已删除这是一行普通代码```markdown
------ a/README.md+++ b/README.md@@ -1,3 +1,4 @@+这是一个真实的 diff 文件示例-所有内容都将保持原样 连空格也不会被移除```--- a/README.md+++ b/README.md@@ -1,3 +1,4 @@+这是一个真实的 diff 文件示例-所有内容都将保持原样 连空格也不会被移除将语法高亮与 Diff 语法结合
```diff lang="js" function thisIsJavaScript() { // 整个代码块按 JavaScript 高亮, // 同时我们仍然可以添加 diff 标记!- console.log('旧的代码将被移除')+ console.log('全新的闪亮代码!') }``````markdown
```diff lang="js" function thisIsJavaScript() { // 整个代码块按 JavaScript 高亮, // 同时我们仍然可以添加 diff 标记!- console.log('旧的代码将被移除')+ console.log('全新的闪亮代码!') }```markdown
#### 标记行内的特定文本function demo() { // 标记行内任何出现的“指定文本” return '支持多次匹配指定文本';}```function demo() { // 标记行内任何出现的“指定文本” return '支持多次匹配指定文本';}正则表达式
```ts /ye[sp]/console.log('单词 yes 和 yep 都将被标记。')``````markdown
```ts /ye[sp]/console.log('单词 yes 和 yep 都将被标记。')```markdown
#### 标记行内标记类型 (mark, ins, del)function demo() { console.log('这些是 inserted 和 deleted 标记类型'); // return 语句使用默认标记类型 return true;}```function demo() { console.log('这些是 inserted 和 deleted 标记类型'); // return 语句使用默认标记类型 return true;}4. 自动换行 (Word Wrap)
为单个代码块配置换行
```js wrap// 开启换行的示例function getLongString() { return '这是一段非常长的字符串,如果不开启自动换行,它很可能超出现在容器的显示范围,除非容器极宽。'}``````markdown
```js wrap// 开启换行的示例function getLongString() { return '这是一段非常长的字符串,如果不开启自动换行,它很可能超出现在容器的显示范围,除非容器极宽。'}```markdown
---// 关闭换行的示例 (wrap=false)function getLongString() { return '这是一段非常长的字符串,如果不开启自动换行,它很可能超出现在容器的显示范围,除非容器极宽。'}```// 关闭换行的示例 (wrap=false)function getLongString() { return '这是一段非常长的字符串,如果不开启自动换行,它很可能超出现在容器的显示范围,除非容器极宽。'}配置换行后的缩进
```js wrap preserveIndent// 保持缩进示例 (默认开启)function getLongString() { return '长字符串换行后会保持与上一行相同的缩进位置。'}``````markdown
```js wrap preserveIndent// 保持缩进示例 (默认开启)function getLongString() { return '长字符串换行后会保持与上一行相同的缩进位置。'}```markdown
---// 关闭保持缩进示例 (preserveIndent=false)function getLongString() { return '长字符串换行后将不再保持缩进,而是从行首开始。'}```// 关闭保持缩进示例 (preserveIndent=false)function getLongString() { return '长字符串换行后将不再保持缩进,而是从行首开始。'}5. 可折叠代码段 (Collapsible Sections)
```js collapse={1-5, 12-14, 21-24}// 这里的初始化样板代码将被折叠import { someBoilerplateEngine } from '@example/some-boilerplate'import { evenMoreBoilerplate } from '@example/even-more-boilerplate'
const engine = someBoilerplateEngine(evenMoreBoilerplate())
// 这部分代码默认可见engine.doSomething(1, 2, 3, calcFn)
function calcFn() { // 您可以设置多个折叠区域 const a = 1 const b = 2 const c = a + b
// 这一行保持可见 console.log(`计算结果: ${a} + ${b} = ${c}`) return c}
// 结尾的样板代码也会被再次折叠engine.closeConnection()engine.freeMemory()engine.shutdown({ reason: 'End of example boilerplate code' })``````markdown
```js collapse={1-5, 12-14, 21-24}// 这里的初始化样板代码将被折叠import { someBoilerplateEngine } from '@example/some-boilerplate'import { evenMoreBoilerplate } from '@example/even-more-boilerplate'
const engine = someBoilerplateEngine(evenMoreBoilerplate())
// 这部分代码默认可见engine.doSomething(1, 2, 3, calcFn)
function calcFn() { // 您可以设置多个折叠区域 const a = 1 const b = 2 const c = a + b
// 这一行保持可见 console.log(`计算结果: ${a} + ${b} = ${c}`) return c}
// 结尾的样板代码也会被再次折叠engine.closeConnection()engine.freeMemory()engine.shutdown({ reason: 'End of example boilerplate code' })```markdown
## 6. 行号 (Line Numbers)
[行号插件](https://expressive-code.com/plugins/line-numbers/)
### 为代码块显示行号// 这个代码块将显示行号console.log('来自第 2 行的问候!')console.log('我在第 3 行')```// 这个代码块将显示行号console.log('来自第 2 行的问候!')console.log('我在第 3 行')```js showLineNumbers=false// 这个代码块禁用了行号console.log('你好?')console.log('抱歉,你知道我在哪一行吗?')``````markdown
```js showLineNumbers=false// 这个代码块禁用了行号console.log('你好?')console.log('抱歉,你知道我在哪一行吗?')```markdown
### 修改起始行号console.log('来自第 5 行的问候!')console.log('我在第 6 行')```console.log('来自第 5 行的问候!')console.log('我在第 6 行')7. 长代码块限高与内部滚动(本站魔改)
官方 Expressive Code 本身不限制代码块高度,一段 80 行的日志能把整篇文章撑到「滑不到底」。本站给它加了一层处理:超过约 17 行就在块内滚动,没滚到底时底部压一道渐隐,提示下方还有内容。
7.1 为什么只写一条 max-height 不生效
第一直觉是给 pre 加 max-height,但你会发现它不起作用。原因是 EC 的 reset 样式里有一条:
.expressive-code :not(:is(svg, svg *)) { max-height: revert; /* 同优先级下会反悔我们的声明 */}revert 会把属性回滚到用户代理样式(也就是 none)。所以我们的选择器权重必须比它高——本站的写法是嵌套在 .expressive-code 下的 .frame pre:
.expressive-code { .frame { @apply !shadow-none relative; /* 去掉默认阴影;渐隐遮罩需要 relative 定位 */
pre { max-height: 22rem; /* 约 17 行,超出滚动 */ overscroll-behavior: contain; /* 滚到头不带动整页一起滚 */ } }}TIP不用嵌套写法时,等价形式是
.expressive-code .frame pre { ... }——两层类选择器,权重高于 reset 的单层:not(...)。关键是别只写一个.frame pre。
7.2 底部渐隐:提示「下面还有」
限高之后最大的问题是读者不知道这块能滚。本站用一个 ::after 伪元素做底部渐变:
.expressive-code .frame.is-clipped::after { content: ""; pointer-events: none; /* 关键:别挡住最后几行代码的选中与点击 */ position: absolute; left: 0; right: 0; bottom: 0; height: 3.5rem; /* 代码块恒为深色底(github-dark),渐变对齐其背景色 */ background: linear-gradient(to top, #24292e 30%, transparent); border-radius: 0 0 var(--radius-large, 0.5rem) var(--radius-large, 0.5rem);}两个细节:
pointer-events: none必须写,否则这道遮罩会挡住底部几行代码的选中、复制和点击- 渐变色要对齐你实际使用的代码主题背景色。本站 EC 主题恒为 github-dark(
#24292e),如果你换成浅色主题,这里的颜色也要跟着换
7.3 JS:只在真的溢出时才显示渐隐
短代码块不该有渐隐条。用一个溢出检测给 frame 挂 is-clipped 类:
/* ===== 长代码块:溢出检测 + 底部渐隐提示 ===== */function initCodeClips() { document.querySelectorAll('.expressive-code pre').forEach((pre) => { const frame = pre.closest('.frame'); if (!frame) return; const clipped = pre.scrollHeight > pre.clientHeight + 4; // +4 容差,防亚像素抖动 frame.classList.toggle('is-clipped', clipped); frame.classList.toggle('is-scrolled-end', !clipped); });}滚到底时把渐隐收掉,否则读完了还压着一道黑:
/* scroll 事件不冒泡,必须用捕获阶段委托 */document.addEventListener('scroll', (e) => { const t = e.target; if (!(t instanceof HTMLElement) || t.tagName !== 'PRE') return; const frame = t.closest('.frame'); if (!frame) return; if (t.scrollTop + t.clientHeight >= t.scrollHeight - 12) { frame.classList.remove('is-clipped'); frame.classList.add('is-scrolled-end'); } else if (t.scrollHeight > t.clientHeight + 4) { frame.classList.add('is-clipped'); frame.classList.remove('is-scrolled-end'); }}, true);IMPORTANT
scroll事件不冒泡——它只在产生滚动的元素自己身上触发。所以要监听页面里所有代码块的滚动,不能把addEventListener('scroll', fn)直接挂在document上收事件,必须传第三个参数true走捕获阶段委托。这是这段逻辑里最容易写错的一处。
7.4 Swup 无刷新导航兼容
本站启用了 Swup,切页时不会重新执行页面脚本。所以初始化函数要挂在两个事件上,并在首次加载时手动跑一次兜底:
document.addEventListener('astro:page-load', initCodeClips); // 首屏 + 视图过渡document.addEventListener('swup:page:view', initCodeClips); // Swup 切页后initCodeClips(); // 兜底7.5 想改高度?
max-height: 22rem 是唯一需要调的数字(约 17 行)。想宽松改 30rem,想紧凑改 16rem;22rem 是「一眼能看完大半屏、又不至于把文章撑爆」的折中值。
NOTE如果某段代码你不希望被限高(比如想完整展示一份长配置),EC 自带
collapse折叠属性其实更好用——见前文第 5 节。限高解决的是「读者不想看但页面被拉长」,折叠解决的是「读者可以自己决定展开」,两者场景不同。