VitePress 集成

VitePress 在底层使用了 Shiki，所以你不需要显式地集成。

VitePress 提供了一些 Shiki 的自定义选项，在 VitePress 文档上查看更多。

Twoslash

要在 Vitepress 中启用 TypeScript Twoslash（类型悬停显示），可以使用我们提供的插件来快速开始，它借助 Floating Vue 在容器外显示具有样式的类型信息。

设置

npm

npm i -D @shikijs/vitepress-twoslash

yarn

yarn add -D @shikijs/vitepress-twoslash

pnpm

pnpm add -D @shikijs/vitepress-twoslash

bun

bun add -D @shikijs/vitepress-twoslash

deno

deno add npm:@shikijs/vitepress-twoslash

在你的 vitepress/config.ts：

.vitepress/config.ts

import { transformerTwoslash } from '@shikijs/vitepress-twoslash'
import { defineConfig } from 'vitepress'

export default defineConfig({
  markdown: {
    codeTransformers: [
      transformerTwoslash() 
    ],
    // 显式加载这些语言以便类型高亮
    languages: ['js', 'jsx', 'ts', 'tsx']
  }
})

然后在你的 .vitepress/theme/index.ts 中，安装 Vue 插件并通过 vitepress-plugin-twoslash/styles.css 导入 CSS。

.vitepress/theme/index.ts

import type { EnhanceAppContext } from 'vitepress'
import TwoslashFloatingVue from '@shikijs/vitepress-twoslash/client'
import Theme from 'vitepress/theme'

import '@shikijs/vitepress-twoslash/style.css'

export default {
  extends: Theme,
  enhanceApp({ app }: EnhanceAppContext) {
    app.use(TwoslashFloatingVue) 
  },
}

关于 style.css

方便起见，vitepress-plugin-twoslash/styles.css 包含了 floating-vue 和 shiki-twoslash/style-rich.css 中的样式，所以你只需要引入这一项。如果你使用的是自定义 floating-vue 样式，或者需要对样式进行更多控制，你可以将它展开成如下几项：

import '@shikijs/vitepress-twoslash/style.css'

// 等同于：
import '@shikijs/twoslash/style-rich.css'
import 'floating-vue/dist/style.css'
import '@shikijs/vitepress-twoslash/style-core.css'

现在，你可以在你的 Markdown 文件中使用 ts twoslash 来启用美观的类型悬停显示。

```ts twoslash
console.log('hello')
//      ^?
```

它会被渲染为：

console.log('hello')

Vue SFC

此外，这个插件集成了 twoslash-vue，所以你可以使用 vue twoslash 高亮 Vue SFC 块：

<script setup>
import { onMounted, ref } from 'vue'

// 响应式状态
const count = ref(0)

// 修改状态并触发更新的函数
function increment() {
  count.value++
}

// 生命周期钩子
onMounted(() => {
  console.log(`The initial count is ${count.value}.`)
})
</script>

<template>
  <button @click="increment">
    Count is: {{ count }}
  </button>
</template>

文件系统缓存

为了加快构建过程，您可以为生成的类型启用文件系统缓存，该缓存可以跨多个构建共享。默认情况下，缓存存储在 .vitepress/cache/twoslash 中，与其他 VitePress 缓存一起。

在您的 .vitepress/config.ts：

.vitepress/config.ts

import { transformerTwoslash } from '@shikijs/vitepress-twoslash'
import { createFileSystemTypesCache } from '@shikijs/vitepress-twoslash/cache-fs'
import { defineConfig } from 'vitepress'

export default defineConfig({
  markdown: {
    codeTransformers: [
      transformerTwoslash({
        typesCache: createFileSystemTypesCache() 
      })
    ]
  }
})

Inline Cache（实验性）

你可以为生成的类型启用内联缓存。@twoslash-cache: ... 会在开发和构建时自动插入到你的代码块中。

./your-file.md

```ts twoslash
// @twoslash-cache: [auto generated]
const a: string = 'foo'
```

要在你的 .vitepress/config.ts 中启用内联缓存，请使用由 createTwoslashWithInlineCache 创建的配置包装器。

.vitepress/config.ts

import { createTwoslashWithInlineCache } from '@shikijs/vitepress-twoslash/cache-inline'
import { defineConfig } from 'vitepress'

const withTwoslashInlineCache = createTwoslashWithInlineCache({ 
  // ... transformerTwoslash 的配置
})

export default withTwoslashInlineCache(
  defineConfig({
    markdown: {
      codeTransformers: [
        // 配置已移至 `createTwoslashWithInlineCache()`
        // transformerTwoslash({ ... })
      ]
    }
  })
)

强制重新生成内联缓存

如果想强制重新生成内联缓存并忽略已有缓存，可以在运行 vitepress CLI 时设置环境变量 TWOSLASH_INLINE_CACHE_IGNORE。

TWOSLASH_INLINE_CACHE_IGNORE=1 vitepress dev
TWOSLASH_INLINE_CACHE_IGNORE=1 vitepress build

移除内联缓存

如果想移除所有内联缓存，可以在运行 vitepress CLI 时设置环境变量 TWOSLASH_INLINE_CACHE_REMOVE。

TWOSLASH_INLINE_CACHE_REMOVE=1 vitepress dev
TWOSLASH_INLINE_CACHE_REMOVE=1 vitepress build