企业官网建设流程全解析

如何用 @unocss/twoslash 在 VitePress 文档代码块中展示 UnoCSS 生成的 CSS？

【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocss

如果你的文档站由 VitePress 驱动，并且用了 UnoCSS 的原子类，读者往往只能看到p-4 text-red这类类名，看不到它们实际编译出的 CSS。@unocss/twoslash是 UnoCSS 提供的 twoslash 集成：它在构建文档时为代码块中的工具类附加悬浮（hover）节点，鼠标移到类名上就能看到 UnoCSS 为该类生成的 CSS 输出。整个过程只需在 VitePress 配置里注册一个 transformer，并在 markdown 代码块上加twoslash标记。

前提条件：你的文档站使用 VitePress（该集成面向 VitePress 文档场景），并且项目已有 UnoCSS 配置（即存在 UnoCSS config 文件，可参考 docs/guide/config-file.md）。

安装依赖

安装@unocss/twoslash：

npm add @unocss/twoslash

官方用法文档（docs/integrations/twoslash.md）给出的 VitePress 配置里，代码 transformer 来自@shikijs/vitepress-twoslash，所以项目中还需要能引入这个包，否则下面的配置无法编译。

在 VitePress 配置中注册 twoslash

修改.vitepress/config.ts，按官方文档的示例注册transformerTwoslash：

import { transformerTwoslash } from '@shikijs/vitepress-twoslash' import { createTwoslasher } from '@unocss/twoslash' import { defineConfig } from 'vitepress' export default defineConfig({ markdown: { codeTransformers: [ transformerTwoslash({ langs: ['vue', 'html'], twoslasher: createTwoslasher(), }), ], }, })

两个关键项的用途（以 docs/integrations/twoslash.md 说明为准）：

• langs: ['vue', 'html']：限定哪些语言围栏的代码块会被处理，示例中只标注vue和html代码块。
• twoslasher: createTwoslasher()：由@unocss/twoslash创建的处理器，负责把代码块里的 UnoCSS 类名转换成带 CSS 输出的 hover 节点。

在 markdown 代码块中启用 twoslash

配置生效后，在 fenced code block 的语言标识后加twoslash标记即可。示例来自官方文档：

<div class="p-4 text-red"></div>

UnoCSS 会把代码块中匹配到的工具类逐个生成 CSS，并挂在对应类名位置上。仓库自带的测试用例展示了两种典型输入：basic.vue（模板中带class="m-1 w-1/2"的div）和 basic.ts（以// @unocss-include开头、类名写在数组字面量中的 TS 代码）。

配置 createTwoslasher 的可选参数

createTwoslasher()支持两个可选参数，用于项目配置不在默认位置或需要先清洗代码的场景：

configPath—— 指定 UnoCSS 配置文件路径。不提供时会沿目录树自动向上查找：

createTwoslasher({ configPath: './my-uno.config.ts', })

preprocess—— 在代码交给 UnoCSS 生成 CSS 之前做自定义转换，只影响生成过程，不影响页面上渲染的代码本身：

createTwoslasher({ preprocess: code => code.replace(/\/\/.*$/gm, ''), })

验证：hover 输出的内容长什么样

生成结果是一组type: 'hover'的节点，text固定为CSS Output，docs字段是格式化的 CSS 代码块，target为对应的类名。以下输出取自仓库测试快照 basic.ts.json，仅作文档示例，说明节点结构，不代表你在自己配置下会得到逐字相同的内容：

{ "type": "hover", "text": "CSS Output", "docs": "```css\n/* layer: default */\n.m-1 {\n margin: 0.25rem;\n}\n```", "start": 37, "target": "m-1", "length": 3, "line": 3, "character": 3 }

验证方式：构建或运行 VitePress 文档站后，打开含twoslash标记的代码块页面，鼠标悬停在工具类（如上例中的m-1）上，应出现标题为CSS Output的悬浮提示，其中是对应类的 CSS 规则。

需要说明的是，生成过程不包含 preflights 与 safelist——@unocss/twoslash的 worker 在调用 UnoCSS 生成时传入了preflights: false, safelist: false（见 worker.ts），所以悬浮提示里只会出现代码块中实际用到的类对应的规则，而不会带上全局基础样式。

限制与边界

• 该集成面向 VitePress 文档站，实现依赖twoslash-protocol（见 package.json），代码块标注经由 Shiki 的 twoslash transformer 完成。
• langs未列出的代码块语言不会被标注；preprocess的转换不会改变渲染出来的代码文本。
• 如果你的 UnoCSS 配置不在默认查找路径内，必须显式传configPath，否则生成器可能加载到非预期的配置。

更多细节（安装、完整配置与选项说明）可查阅 docs/integrations/twoslash.md。

【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocss