代码块

更新于 2026年11月1日

代码块就是 <pre><code>，由主题以等宽字体设置样式。每个代码块都有一个复制按钮和一个自动换行长行的按钮。其中的代码需要转义： < 写作 <，& 写作 &。代码块的标签页在代码标签页中介绍。

<pre><code>const greeting = "&lt;hello&gt;"</code></pre>

```
const greeting = "<hello>"
```

渲染为：

const greeting = "<hello>"

语法高亮

<code> 上的 language-* 类会在构建时使用 VS Code 的 TextMate 语法为代码块着色，输出与 Shiki 相同，并提供跟随读者偏好的浅色和深色主题（见语法主题）。内置支持 220 多种语言及其常用别名（ts、sh、yml）；未知语言或自带标记的代码块保持纯文本。

<pre><code class="language-rust">fn main() {
    println!("hello");
}</code></pre>

```rust
fn main() {
    println!("hello");
}
```

渲染为：

fn main() {
    println!("hello");
}

标题

<pre> 上的 data-title 会为代码块添加标题栏，通常是文件名；无论代码块是否高亮都有效。

<pre data-title="htmlpress.yaml"><code class="language-yaml">title: Htmlpress</code></pre>

```yaml title="htmlpress.yaml"
title: Htmlpress
```

渲染为：

htmlpress.yaml

title: Htmlpress

行高亮

高亮代码块上的 data-lines 用于标记行，从 1 开始计数：可以是单行或范围，以逗号分隔。

<pre><code class="language-js" data-lines="2">…</code></pre>

```js lines="2"
…
```

const a = 1
const b = 2
const c = 3

单词高亮

高亮代码块上的 data-words 会标记每个逗号分隔单词的所有出现位置。被语法拆分成两个词法单元的单词不会被标记。

<pre><code class="language-js" data-words="greeting">…</code></pre>

```js words="greeting"
…
```

const greeting = "hello"
console.log(greeting)

行号

高亮代码块上的 data-line-numbers 会为各行编号； data-line-numbers="10" 从 10 开始。复制按钮不会复制行号。

10const a = 1
11const b = 2

差异行

高亮代码块上的 data-add 和 data-remove 将行标记为新增或删除，并带有复制按钮会忽略的 + 或 −。在终端中，<ins> 和 <del> 会把输出着色为绿色和红色。

<pre><code class="language-js" data-remove="1" data-add="2">…</code></pre>

```js remove="1" add="2"
…
```

const port = 8080
const port = 8000
serve(port)

聚焦行

高亮代码块上的 data-focus 会让其他所有行变暗，直到读者指向该代码块。

import { build } from "htmlpress"
await build("docs")
console.log("done")

错误和警告

data-error 和 data-warning 以红色和黄色标记行。

undefinedCall()
const unused = 1

每种行标记都接受与 data-lines 相同的列表，例如 2,4-5，无效的列表会导致构建失败。

可折叠代码

用 <details> 包裹较长的代码块，可将其隐藏在 <summary> 之后：

<details>
  <summary>The full config</summary>
  <pre><code>…</code></pre>
</details>

:::details[The full config]
```
…
```
:::

<pre> 上的 data-collapse 只显示前几行，代码块下方会出现一个“展开”栏用于显示其余部分；没有脚本时，代码块改为可滚动。不超过该高度的代码块不会出现展开栏。

<pre data-collapse="5"><code class="language-yaml">…</code></pre>

```yaml collapse="5"
…
```

steps:
  build: 1
  build: 2
  build: 3
  build: 4
  build: 5
  build: 6
  build: 7
  build: 8
  build: 9
  build: 10
  build: 11
  build: 12

ANSI 输出

language-ansi 代码块会渲染终端输出中的颜色转义序列，可以原样书写，也可以写作 ：支持 16 色、256 色和真彩色形式，以及粗体、暗淡、斜体、下划线和删除线。其他转义序列会被丢弃。

<pre><code class="language-ansi">&#27;[32m✓&#27;[0m built 48 pages
&#27;[1;31merror&#27;[0m: index.html: no title</code></pre>

<pre><code class="language-ansi">&#27;[32m✓&#27;[0m built 48 pages
&#27;[1;31merror&#27;[0m: index.html: no title</code></pre>

渲染为：

✓ built 48 pages
error: index.html: no title

语言图标

带标题的代码块会在标题栏中显示其语言的 logo：TypeScript、JavaScript、React（jsx、tsx）、Python、Rust 和 shell，与 Livemark 显示的一致；其他语言则显示通用文件图标。

main.rs

fn main() {}

build.sh

htmlpress build docs

TypeScript 支持

像 Twoslash 那样在悬停时显示类型信息需要 TypeScript 编译器，而单个 Rust 二进制文件并不包含它。TypeScript 代码块与其他代码块一样进行高亮。

NPM 命令

在 <htmlpress-package-tabs> 中写一条 npm 或 npx 命令，构建时会把它转换为 npm、pnpm、yarn 和 bun 的标签页，并在全站同步。其他行保持原样。

<htmlpress-package-tabs>
  <pre><code>npm install --save-dev gethtmlpress</code></pre>
</htmlpress-package-tabs>

```npm
npm install --save-dev gethtmlpress
```

渲染为：

npm install --save-dev gethtmlpress

pnpm add -D gethtmlpress

yarn add -D gethtmlpress

bun add -D gethtmlpress

终端

<htmlpress-terminal> 中的 <pre> 看起来像一个终端窗口，在两种主题下都是深色，并以 title 命名。其中，<kbd> 表示输入的命令（会自动添加提示符），<samp> 表示普通输出，<ins>、<del> 和 <mark> 分别表示绿色、红色和黄色的输出。

<htmlpress-terminal title="zsh">
  <pre><kbd>htmlpress build docs</kbd>
<samp>built 7 pages…</samp>
<ins>✓ ready</ins></pre>
</htmlpress-terminal>

<htmlpress-terminal title="zsh">
  <pre><kbd>htmlpress build docs</kbd>
<samp>built 7 pages…</samp>
<ins>✓ ready</ins></pre>
</htmlpress-terminal>

渲染为：

htmlpress build docs
built 7 pages and 0 files into docs/.htmlpress/build
✓ ready
✗ 1 page failed
! 1 warning

用 ❤ 和 Htmlpress 构建