个人开发学习资料库

Appearance

VitePress代码展示优化 ​

VitePress 基于 Shiki + 自家扩展，代码块的"花活"其实很多，下面列 8 个最实用的优化点。

1. 行高亮 {1,3-5} ​

最基础也最常用，高亮指定行，引导读者视线。

md
```js {2,4-6}
const a = 1
const b = 2 // 高亮
const c = 3
const d = 4 // 高亮
const e = 5 // 高亮
const f = 6 // 高亮
```
js
const a = 1
const b = 2 // 高亮
const c = 3
const d = 4 // 高亮
const e = 5 // 高亮
const f = 6 // 高亮

2. Diff 风格 [!code ++] / [!code --] ​

模拟 Git diff，做"改造前后对比"特别清晰。

md
```js
export default {
  data () {
    return {
      msg: 'Removed'
      msg: 'Added'
    }
  }
}
```

效果是绿色 + 行和红色 - 行，左侧带 ± 标记。

3. Focus 聚焦 [!code focus] / [!code focus:N] ​

让目标行清晰、其余行变模糊（hover 时才完全显示），讲解长代码里某几行时无敌好用。

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

加数字 [!code focus:3] 表示从当前行开始连续聚焦 3 行。

4. 错误 / 警告高亮 [!code error] / [!code warning] ​

用红/黄背景标出"反例代码"或"易踩的坑"，比单纯注释直观得多。

md
```js
export default {
  data () {
    return {
      msg: 'Error',   
      msg: 'Warning', 
    }
  }
}
```

5. 行号 + 起始行号 ​

全局可在 config.ts 里开 markdown.lineNumbers: true；单块也可单独控制：

md
```ts {1}
// 这块强制显示行号
```

```ts:line-numbers=10 {1}
// 从第 10 行开始计数（适合贴某文件片段）
```

写"接 xx 行的代码"时非常有用。

ts
// 这块强制显示行号
ts
// 从第 10 行开始计数（适合贴某文件片段）

6. 代码块标题 / 文件名 ​

给代码块挂个文件名，读者一眼知道改的是哪个文件。

md
```ts [src/router/index.ts]
import { createRouter } from 'vue-router'
```

或者老语法：

md
```ts{1} title="src/router/index.ts"

VitePress 会渲染成一个带文件名的 tab 头。

ts
import { createRouter } from 'vue-router'
ts
import { createRouter } from 'vue-router'

7. 代码组 Code Groups（多语言 / 多包管理器 Tab） ​

最适合"npm / yarn / pnpm 三选一"或"Vue 2 vs Vue 3"对比。

md
::: code-group

```sh [npm]
npm i vitepress
```

```sh [pnpm]
pnpm add vitepress
```

```sh [yarn]
yarn add vitepress
```

:::

渲染出来就是一个 Tab 切换组件，按习惯选。

sh
npm i vitepress
sh
pnpm add vitepress
sh
yarn add vitepress

8. 代码片段导入 <<< （Snippet Import） ​

不要把代码贴到 md 里，而是直接引用真实源文件，文档永不脱钩。

md
<<< @/demo.ts

<!-- 指定区域 -->
<<< @/demo.ts#snippet

<!-- 指定语言和高亮行 -->
<<< @/demo.ts{2,4-6 ts:line-numbers}

在源文件里用 // #region snippet … // #endregion snippet 框出片段。

ts
// #region snippet
console.log("hello world");
// #endregion snippet

const a = 1;
console.log(a);
ts
console.log("hello world");
ts
// #region snippet
console.log("hello world");
// #endregion snippet

const a = 1;
console.log(a);

小技巧 ​

  • 组合使用：[!code focus] + [!code ++] 可以叠加，做"聚焦 + 新增"的演示效果。
  • whitespace 可视化：```ts:no-v-pre 关掉 Vue 解析，避免 被当模板。
  • 主题切换：config.ts 里 markdown.theme: { light: 'github-light', dark: 'one-dark-pro' }，跟随站点深浅色。
  • 自定义容器配色：把上面这些标记的 CSS 变量在 .vp-doc 里覆盖，可以做出你专属配色（比如把 focus 的模糊度从 0.4 调到 0.2）。