特性支持

约 1682 字大约 6 分钟

2024-04-04

主题在代码高亮功能上，进一步支持了更多的特性，它们能够帮助你的代码块更加具备表达力。

代码块标题

在 ``` [lang] 之后添加 title="xxxx" ，可以为当前代码块添加标题

输入：

```json title="package.json"
{
  "name": "vuepress-theme-plume"
}
```

输出：

package.json
{
  "name": "vuepress-theme-plume"
}

代码行号

主题默认显示代码行号，它通过 codeHighlighter.line-numbers 来控制。

.vuepress/config.ts
export default defineUserConfig({
  theme: plumeTheme({
    codeHighlighter: {
      lineNumbers: true, 
    }
  })
})

你还可以通过 :line-numbers / :no-line-numbers 来控制当前代码块是否显示代码行号。还可以通过在 :line-numbers 之后添加 = 来自定义起始行号，例如 :line-numbers=2 表示代码块中的行号从 2 开始。

输入：

```ts:line-numbers
// 启用行号
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

```ts:no-line-numbers
// 行号已禁用
const line3 = 'This is line 3'
const line4 = 'This is line 4'
```

```ts:line-numbers=2
// 行号已启用，并从 2 开始
const line3 = 'This is line 3'
const line4 = 'This is line 4'
```

输出：

// 启用行号
const line2 = 'This is line 2'
const line3 = 'This is line 3'

// 行号已禁用
const line3 = 'This is line 3'
const line4 = 'This is line 4'

// 行号已启用，并从 2 开始
const line3 = 'This is line 3'
const line4 = 'This is line 4'

在代码块中实现行高亮

在 [lang] 之后紧跟随 {xxxx} ，可以实现行高亮，其中 xxx 表示要高亮的行号。

输入：

```js{4}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```

输出：

export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}

除了单行之外，还可以指定多个单行、多行，或两者均指定：

多行：例如 {5-8}、{3-10}、{10-17}
多个单行：例如 {4,7,9}
多行与单行：例如 {4,7-13,16,23-27,40}

输入：

```js{1,4,6-8}
export default { // Highlighted
  data () {
    return {
      msg: `Highlighted!
      This line isn't highlighted,
      but this and the next 2 are.`,
      motd: 'VitePress is awesome',
      lorem: 'ipsum'
    }
  }
}
```

输出：

export default { // Highlighted
  data () {
    return {
      msg: `Highlighted!
      This line isn't highlighted,
      but this and the next 2 are.`,
      motd: 'VitePress is awesome',
      lorem: 'ipsum'
    }
  }
}

也可以使用 // [!code highlight] 注释实现行高亮。

输入：

```js
export default {
  data() {
    return {
      msg: 'Highlighted!' // [!code highlight]
    }
  }
}
```

输出：

export default {
  data() {
    return {
      msg: 'Highlighted!'
    }
  }
}

代码块中聚焦

在某一行上添加 // [!code focus] 注释将聚焦它并模糊代码的其他部分。

此外，可以使用 // [!code focus:<lines>] 定义要聚焦的行数。

输入：

```js
export default {
  data() {
    return {
      msg: 'Focused!' // [!code focus]
    }
  }
}
```

输出：

export default {
  data() {
    return {
      msg: 'Focused!'
    }
  }
}

在不同的语言代码块中，应该使用该语言的有效的行注释语法

比如在 bash 代码块中，应该使用 # [!code focus]

```bash
mkdir hello && cd hello  # [!code focus]
pnpm install
```

mkdir hello && cd hello
pnpm install

代码块中的颜色差异

在某一行添加 // [!code --] 或 // [!code ++] 注释将会为该行创建 diff，同时保留代码块的颜色。

输入：

```js
export default {
  data() {
    return {
      error: 'Removed', // [!code --]
      warning: 'Added' // [!code ++]
    }
  }
}
```

输出：

export default {
  data() {
    return {
      error: 'Removed',
      warning: 'Added'
    }
  }
}

在不同的语言代码块中，应该使用该语言的有效的行注释语法

比如在 bash 代码块中，应该使用 # [!code ++]

```bash
mkdir hello && cd hello  # [!code ++]
```

mkdir hello && cd hello

高亮“错误”和“警告”

在某一行添加 // [!code warning] 或 // [!code error] 注释将会为该行相应的着色。

输入：

```js
export default {
  data() {
    return {
      error: 'Error', // [!code error]
      warning: 'Warning' // [!code warning]
    }
  }
}
```

输出：

export default {
  data() {
    return {
      error: 'Error',
      warning: 'Warning'
    }
  }
}

在不同的语言代码块中，应该使用该语言的有效的行注释语法

比如在 bash 代码块中，应该使用 # [!code warning]

```bash
mkdir hello && cd hello  # [!code warning]
```

mkdir hello && cd hello

代码块中词高亮

输入：

```ts
export function foo() { // [!code word:Hello]
  const msg = 'Hello World'
  console.log(msg) // prints Hello World
}
```

输出：

export function foo() {
  const msg = 'Hello World'
  console.log(msg) // prints Hello World
}

你还可以指定高亮显示的次数，例如 [!code word:options:2] 会高亮显示近两个 options。

输入：

```ts
// [!code word:options:2]
const options = { foo: 'bar' }
options.foo = 'baz'
console.log(options.foo) // 这个不会被高亮显示
```

输出：

const options = { foo: 'bar' }
options.foo = 'baz'
console.log(options.foo) // 这个不会被高亮显示

在不同的语言代码块中，应该使用该语言的有效的行注释语法

比如在 bash 代码块中，应该使用 # [!code word:hello]

```bash
mkdir hello && cd hello  # [!code word:hello]
```

mkdir hello && cd hello

代码块中的空白符

将空白字符（Tab 和空格）渲染为可见状态。

在代码块后面添加 :whitespace。

渲染每行代码行前的空格：

输入：

```xml :whitespace
<catalog>
    <book>
        <title>Everyday Italian</title>
    </book>
</catalog>
```

输出：

<catalog>
    <book>
        <title>Everyday Italian</title>
    </book>
</catalog>

渲染每行代码行前的 Tab ：

输入：

```xml :whitespace
<catalog>
	<book>
		<title>Everyday Italian</title>
	</book>
</catalog>
```

输出：

<catalog>
	<book>
		<title>Everyday Italian</title>
	</book>
</catalog>

渲染所有的空格：

输入：

```js :whitespace=all
function foo( ) {
  return 'Hello World'  
}
```

输出：

function foo( ) {
  return 'Hello World'  
}

还可以在 codeHighlighter 中全局启用 whitespace 功能：

.vuepress/config.ts
export default defineUserConfig({
  theme: plumeTheme({
    codeHighlighter: {
      whitespace: true, 
    }
  })
})

全局启用时，可以使用 :no-whitespace 来单独为某一代码块禁用 whitespace 功能。

折叠代码块

有时候，代码块会很长，对于阅读其它部分的内容时，会显得很麻烦，影响阅读体验，这时候可以折叠代码块。

在代码块后面添加 :collapsed-lines，即可折叠代码块，默认从第 15 行开始折叠。

输入：

```css :collapsed-lines
html {
  margin: 0;
  background: black;
  height: 100%;
}

... more code
```

输出：

html {
  margin: 0;
  background: black;
  height: 100%;
}

body {
  margin: 0;
  width: 100%;
  height: inherit;
}

/* the three main rows going down the page */

body > div {
  height: 25%;
}

.thumb {
  float: left;
  width: 25%;
  height: 100%;
  object-fit: cover;
}

.main {
  display: none;
}

.blowup {
  display: block;
  position: absolute;
  object-fit: contain;
  object-position: center;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  z-index: 2000;
}

.darken {
  opacity: 0.4;
}

还可以指定起始折叠行。:collapsed-lines=10 表示从第十行开始折叠。

输入：

```css :collapsed-lines=10
html {
  margin: 0;
  background: black;
  height: 100%;
}

... more code
```

输出：

html {
  margin: 0;
  background: black;
  height: 100%;
}

body {
  margin: 0;
  width: 100%;
  height: inherit;
}

/* the three main rows going down the page */

body > div {
  height: 25%;
}

.thumb {
  float: left;
  width: 25%;
  height: 100%;
  object-fit: cover;
}

.main {
  display: none;
}

.blowup {
  display: block;
  position: absolute;
  object-fit: contain;
  object-position: center;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  z-index: 2000;
}

.darken {
  opacity: 0.4;
}

还可以在 codeHighlighter 中全局启用 collapsed-lines 功能：

.vuepress/config.ts
export default defineUserConfig({
  theme: plumeTheme({
    codeHighlighter: {
      collapsedLines: true
    }
  })
})

全局启用时，可以使用 :no-collapsed-lines 来单独为某一代码块禁用 collapsed-lines 功能。

代码块中的缩进引导线

此功能默认不启用，需要在 codeHighlighter 中全局启用 renderIndentGuides 功能。

.vuepress/config.ts
export default defineUserConfig({
  theme: plumeTheme({
    codeHighlighter: {
      renderIndentGuides: true
    }
  })
})

正如上方的代码块，启用后，会为代码块添加缩进引导线。

代码块中的颜色括号

此功能默认不启用，需要在 codeHighlighter 中全局启用 colorizedBrackets 功能。

.vuepress/config.ts
export default defineUserConfig({
  theme: plumeTheme({
    codeHighlighter: {
      colorizedBrackets: true
    }
  })
})

将代码块中的 {} 和 () 根据嵌套层级，渲染为颜色不同的括号。

贡献者

pengzhanbo

Mister-Hope

更新日志

2026/6/8 05:48

查看所有更新日志

36e9e-feat(theme): add shiki renderIndentGuides transformer, close #917 (#919)于 2026/6/8
9b9f8-style: lint fix于 2026/3/5
4d236-feat(theme)!: add collections support (#704)于 2025/10/7
6ca72-docs: update code block features于 2025/4/28
0fd6c-refactor(theme): improve types and flat config (#524)于 2025/3/15
b8b32-feat!: remove plugin-shikiji, migrate to @vuepress/plugin-shiki, close #489 (#508)于 2025/3/5
0c53b-docs: improve docs (#332)于 2024/11/8
1ff77-docs: update docs于 2024/8/13
12bee-style: lint fix于 2024/6/25
4c63f-chore: tweak于 2024/5/30

集合

markdown

代码块

代码演示

图表

资源嵌入

自定义首页

特性支持

代码块标题

代码行号

在代码块中实现行高亮

代码块中聚焦

代码块中的颜色差异

高亮“错误”和“警告”

代码块中词高亮

代码块中的空白符

折叠代码块

代码块中的缩进引导线

代码块中的颜色括号

贡献者

更新日志