feat: introduce vitepress-plugin-twoslash

Author: antfu

docs/.vitepress/config.ts

@@ -1,10 +1,9 @@
 import type { DefaultTheme } from 'vitepress'
 import { defineConfig } from 'vitepress'
-import { transformerTwoSlash } from 'shikiji-twoslash'
 import { bundledThemes } from 'shikiji'
+import { defaultInfoProcessor, transformerTwoslash } from 'vitepress-plugin-twoslash'
 import { version } from '../../package.json'
 import vite from './vite.config'
-import { rendererFloatingVue } from './renderer-floating-vue'
 
 const GUIDES: DefaultTheme.NavItemWithLink[] = [
   { text: 'Getting Started', link: '/guide/' },
@@ -55,9 +54,14 @@ export default defineConfig({
       }))
     },
     codeTransformers: [
-      transformerTwoSlash({
-        explicitTrigger: true,
-        renderer: rendererFloatingVue(),
+      transformerTwoslash({
+        processHoverInfo(info) {
+          return defaultInfoProcessor(info)
+            // Remove shikiji_core namespace
+            .replace(/\bshikiji_core\./g, '')
+            // Remove member access
+            .replace(/^[a-zA-Z0-9_]*(\<[^\>]*\>)?\./, '')
+        },
       }),
       {
         // Render custom themes with codeblocks
@@ -92,21 +96,7 @@ export default defineConfig({
           return code
         },
       },
-      {
-        name: 'shikiji:vitepress-patch',
-        preprocess(_, options) {
-          const cleanup = options.transformers?.find(i => i.name === 'vitepress:clean-up')
-          if (cleanup)
-            options.transformers?.splice(options.transformers.indexOf(cleanup), 1)
 
-          // Disable v-pre for twoslash, because we need render it with FloatingVue
-          if (options.meta?.__raw?.includes('twoslash')) {
-            const vPre = options.transformers?.find(i => i.name === 'vitepress:v-pre')
-            if (vPre)
-              options.transformers?.splice(options.transformers.indexOf(vPre), 1)
-          }
-        },
-      },
       {
         name: 'shikiji:remove-escape',
         postprocess(code) {

docs/.vitepress/theme/index.ts

@@ -1,23 +1,15 @@
 // https://vitepress.dev/guide/custom-theme
-import { h } from 'vue'
 import Theme from 'vitepress/theme'
+import TwoSlashFloatingVue from 'vitepress-plugin-twoslash/client'
 import 'uno.css'
-import 'shikiji-twoslash/style-rich.css'
-import 'floating-vue/dist/style.css'
 import './style.css'
-import './custom.css'
 import { createPinia } from 'pinia'
-import FloatingVue from 'floating-vue'
+import type { EnhanceAppContext } from 'vitepress'
 
 export default {
   extends: Theme,
-  Layout: () => {
-    return h(Theme.Layout, null, {})
-  },
-  enhanceApp({ app }: any) {
+  enhanceApp({ app }: EnhanceAppContext) {
     app.use(createPinia())
-
-    FloatingVue.options.themes.menu.delay = { show: 0, hide: 0 }
-    app.use(FloatingVue)
+    app.use(TwoSlashFloatingVue)
   },
 }

docs/packages/twoslash.md

@@ -187,40 +187,4 @@ app.innerHTML = await codeToHtml(source, {
 
 ## Integrations
 
-### VitePress
-
-VitePress uses Shikiji for syntax highlighting since [`1.0.0-rc.30`](https://github.com/vuejs/vitepress/blob/main/CHANGELOG.md#100-rc30-2023-11-23). To use this transformer, you can add it to the `markdown.codeTransformers` option in your VitePress config file.
-
-```ts twoslash
-// .vitepress/config.ts
-import { defineConfig } from 'vitepress'
-import { rendererRich, transformerTwoSlash } from 'shikiji-twoslash'
-
-export default defineConfig({
-  markdown: {
-    codeTransformers: [
-      transformerTwoSlash({
-        // This makes TwoSlash only run on code blocks with `twoslash` presented in the codeframe
-        explicitTrigger: true,
-        // Use the rich renderer
-        renderer: rendererRich({
-          // This makes VitePress ignore the additional meta DOM on copy
-          // Available since VitePress 1.0.0-rc.33
-          classExtra: 'vp-copy-ignore',
-        }),
-      })
-    ]
-  },
-})
-```
-
-And import the CSS in your `.vitepress/theme/index.ts`
-
-```ts
-// .vitepress/theme/index.ts
-import 'shikiji-twoslash/style-rich.css'
-
-export default {
-  // ...
-}
-```
+- [VitePress](/packages/vitepress#twoslash) - Enable TwoSlash support in VitePress.

docs/packages/vitepress.md

@@ -1,5 +1,65 @@
 # VitePress Integration
 
-You don't need explicit integration in [VitePress](https://vitepress.dev/) as VitePress already uses Shikiji under the hood.
+[VitePress](https://vitepress.dev/) uses Shikiji under the hood, so you don't need explicit integration.
 
 VitePress provides [a few options for customizing Shikiji](https://github.com/vuejs/vitepress/blob/main/src/node/markdown/markdown.ts#L66-L112). Learn more about them in the [VitePress documentation](https://vitepress.dev/reference/site-config#markdown).
+
+## TwoSlash
+
+To enable [TypeScript TwoSlash](/packages/twoslash) (type hover on code snippets) in VitePress, we provide a VitePress plugin for easy setup. Pre-styled, with [Floating Vue](https://floating-vue.starpad.dev/) to display the type information out side of the code container.
+
+<Badges name="vitepress-plugin-twoslash" />
+
+```bash
+npm i -D vitepress-plugin-twoslash
+```
+
+In your [`.vitepress/config.ts`](https://vitepress.dev/reference/site-config):
+
+```ts twoslash
+// .vitepress/config.ts
+import { defineConfig } from 'vitepress'
+import { transformerTwoslash } from 'vitepress-plugin-twoslash' // [!code hl]
+
+export default defineConfig({
+  markdown: {
+    codeTransformers: [
+      transformerTwoslash() // [!code hl]
+    ]
+  }
+})
+```
+
+And then in your [`.vitepress/theme/index.ts`](https://vitepress.dev/guide/custom-theme):
+
+```ts twoslash
+// @noErrors: true
+// .vitepress/theme/index.ts
+import Theme from 'vitepress/theme'
+import TwoSlashFloatingVue from 'vitepress-plugin-twoslash/client' // [!code hl]
+import './custom-style.css'
+import type { EnhanceAppContext } from 'vitepress'
+
+export default {
+  extends: Theme,
+  enhanceApp({ app }: EnhanceAppContext) {
+    app.use(TwoSlashFloatingVue) // [!code hl]
+  },
+}
+```
+
+That's it, you can now use `ts twoslash` in your markdown files to enable the beautiful type hover.
+
+````md
+```ts twoslash
+console.log('hello')
+//      ^?
+```
+````
+
+It will be rendered as:
+
+```ts twoslash
+console.log('hello')
+//      ^?
+```

package.json

@@ -57,6 +57,7 @@
     "typescript": "^5.3.3",
     "unbuild": "^2.0.0",
     "vite": "^5.0.11",
+    "vitepress-plugin-twoslash": "workspace:*",
     "vitest": "^1.1.3",
     "vue-tsc": "^1.8.27",
     "wrangler": "^3.22.3"

packages/vitepress-plugin-twoslash/README.md

@@ -0,0 +1,9 @@
+# vitepress-plugin-twoslash
+
+Enable TwoSlash support in VitePress.
+
+[Documentation](https://shikiji.netlify.app/packages/vitepress#twoslash)
+
+## License
+
+MIT

packages/vitepress-plugin-twoslash/build.config.ts

@@ -0,0 +1,17 @@
+import { defineBuildConfig } from 'unbuild'
+
+export default defineBuildConfig({
+  entries: [
+    'src/index.ts',
+    'src/client.ts',
+  ],
+  declaration: true,
+  rollup: {
+    emitCJS: false,
+  },
+  externals: [
+    'hast',
+    'vitepress-plugin-twoslash',
+    'vitepress-plugin-twoslash/style.css',
+  ],
+})

packages/vitepress-plugin-twoslash/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "vitepress-plugin-twoslash",
+  "type": "module",
+  "version": "0.9.0-0",
+  "description": "Enable TwoSlash support in VitePress",
+  "author": "Anthony Fu <anthonyfu117@hotmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/antfu/shikiji#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/antfu/shikiji.git",
+    "directory": "packages/vitepress-plugin-twoslash"
+  },
+  "bugs": "https://github.com/antfu/shikiji/issues",
+  "keywords": [
+    "shiki",
+    "twoslash",
+    "vitepress-plugin"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./client": {
+      "types": "./dist/client.d.mts",
+      "default": "./dist/client.mjs"
+    },
+    "./style.css": "./style.css"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "typesVersions": {
+    "*": {
+      "./client": [
+        "./dist/client.d.mts"
+      ],
+      "*": [
+        "./dist/index.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "*.css",
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "dev": "unbuild --stub",
+    "prepublishOnly": "nr build"
+  },
+  "dependencies": {
+    "floating-vue": "^5.0.2",
+    "mdast-util-from-markdown": "^2.0.0",
+    "mdast-util-gfm": "^3.0.0",
+    "mdast-util-to-hast": "^13.0.2",
+    "shikiji": "workspace:*",
+    "shikiji-twoslash": "workspace:*",
+    "vue": "^3.4.7"
+  }
+}

packages/vitepress-plugin-twoslash/src/client.ts

@@ -0,0 +1,30 @@
+import 'shikiji-twoslash/style-rich.css'
+import 'floating-vue/dist/style.css'
+import 'vitepress-plugin-twoslash/style.css'
+
+import type { Plugin } from 'vue'
+import FloatingVue from 'floating-vue'
+
+export type FloatingVueConfig = Parameters<(typeof FloatingVue)['install']>[1]
+
+/**
+ * Vue plugin to install FloatingVue with styles.
+ *
+ * Import this function in `.vitepress/theme/index.ts` and use `app.use(TwoSlashFloatingVue)` inside the `enhanceApp` hook.
+ */
+const TwoSlashFloatingVue: Plugin<[FloatingVueConfig?]> = {
+  install: (app, options: FloatingVueConfig = {}) => {
+    app.use(FloatingVue, {
+      ...options,
+      themes: {
+        twoslash: {
+          $extend: 'menu',
+          delay: { show: 0, hide: 0 },
+        },
+        ...options.theme,
+      },
+    })
+  },
+}
+
+export default TwoSlashFloatingVue