feat(docs): support twoslash (#706)

Co-authored-by: 三咲智子 Kevin Deng <sxzz@sxzz.moe>

Author: zhiyuanzmj

docs/.vitepress/config.ts

@@ -1,8 +1,26 @@
+import { createRequire } from 'node:module'
 import { defineConfig } from 'vitepress'
 import { withPwa } from '@vite-pwa/vitepress'
+import { transformerTwoslash } from '@shikijs/vitepress-twoslash'
+import ts from 'typescript'
 import { docsLink } from '../../macros'
 import { getLocaleConfig, pwa } from './configs'
 
+const require = createRequire(import.meta.url)
+
+// Volar plugins
+const defineOptions = require('@vue-macros/volar/define-options')
+const defineEmit = require('@vue-macros/volar/define-emit')
+const defineProp = require('@vue-macros/volar/define-prop')
+const defineProps = require('@vue-macros/volar/define-props')
+const definePropsRefs = require('@vue-macros/volar/define-props-refs')
+const defineSlots = require('@vue-macros/volar/define-slots')
+const defineModels = require('@vue-macros/volar/define-models')
+const exportExpose = require('@vue-macros/volar/export-expose')
+const exportRender = require('@vue-macros/volar/export-render')
+const jsxDirective = require('@vue-macros/volar/jsx-directive')
+const booleanProp = require('@vue-macros/volar/boolean-prop')
+
 export default withPwa(
   defineConfig({
     lastUpdated: true,
@@ -40,5 +58,33 @@ export default withPwa(
       hostname: docsLink,
     },
     pwa,
+    markdown: {
+      codeTransformers: [
+        transformerTwoslash({
+          twoslashOptions: {
+            compilerOptions: {
+              jsx: ts.JsxEmit.Preserve,
+              jsxFactory: 'vue',
+              types: ['unplugin-vue-macros/macros-global', 'vue/jsx'],
+            },
+            vueCompilerOptions: {
+              plugins: [
+                defineOptions,
+                defineModels,
+                defineSlots,
+                defineEmit,
+                defineProp,
+                defineProps,
+                definePropsRefs,
+                exportRender,
+                exportExpose,
+                jsxDirective,
+                booleanProp,
+              ],
+            },
+          },
+        }),
+      ],
+    },
   }),
 )

docs/.vitepress/theme/index.ts

@@ -1,12 +1,14 @@
 import Theme from 'vitepress/theme'
 import { NolebaseGitChangelogPlugin } from '@nolebase/vitepress-plugin-git-changelog/client'
+import TwoslashFloatingVue from '@shikijs/vitepress-twoslash/client'
 import WarnBadge from '../components/WarnBadge.vue'
 import StabilityLevel from '../components/StabilityLevel.vue'
 import Layout from './Layout.vue'
 import type { EnhanceAppContext } from 'vitepress'
 import 'uno.css'
 import './style.css'
 import '@nolebase/vitepress-plugin-git-changelog/client/style.css'
+import '@shikijs/vitepress-twoslash/style.css'
 
 export default {
   ...Theme,
@@ -26,5 +28,6 @@ export default {
         },
       ],
     })
+    app.use(TwoslashFloatingVue)
   },
 }

docs/features/better-define.md

@@ -17,22 +17,27 @@ With enabling `betterDefine`, imported types are supported in `<script setup>` t
 
 ::: code-group
 
-```vue [App.vue]
+```vue twoslash [App.vue]
 <script setup lang="ts">
+// #region basic
+type BaseProps = {
+  title: string
+}
+
+export type { BaseProps }
+// #endregion basic
+// ---cut---
+// @noErrors
 import type { BaseProps } from './types'
 
 interface Props extends BaseProps {
   foo: string
 }
-defineProps<Props>()
+const props = defineProps<Props>()
 </script>
 ```
 
-```ts [types.ts]
-export interface BaseProps {
-  title: string
-}
-```
+<<< ./better-define.md#basic{ts} [types.ts]
 
 :::
 

docs/features/boolean-prop.md

@@ -26,18 +26,35 @@ interface Options {
 
 ## Usage
 
-```vue
+<!-- prettier-ignore-start -->
+```vue twoslash
+<script setup>
+import type { FunctionalComponent } from 'vue'
+
+export const Comp: FunctionalComponent<
+  {
+    checked: true,
+    enabled: false,
+  },
+> = () => null
+// ---cut---
+// @noErrors
+import Comp from './Comp.vue'
+</script>
+
 <template>
   <Comp checked !enabled />
+  //             ^?
 </template>
 ```
+<!-- prettier-ignore-end -->
 
-```vue
+```vue twoslash
 <script setup lang="ts">
 // Comp.vue
 defineProps<{
-  checked?: any
-  enabled: boolean
+  checked: true
+  enabled: false
 }>()
 </script>
 ```

docs/features/export-expose.md

@@ -23,12 +23,13 @@ Support these syntaxes:
 
 ### 1. local variable/function/class
 
-```vue
+```vue twoslash
 <script setup lang="ts">
 export const foo: string = 'foo',
   bar = 10
 export let baz: string | undefined
 export var qux = fn()
+// @errors: 2448 2454 2695
 export const { a, b, c } = { a: 1, b: 2, c: 3 }
 
 export function fn() {}
@@ -38,8 +39,8 @@ export class A {}
 
 ::: details Compiled Code
 
-```vue
-<script lang="ts">
+```vue twoslash
+<script setup lang="ts">
 const foo: string = 'foo',
   bar = 10
 let baz: string | undefined
@@ -67,16 +68,20 @@ defineExpose({
 
 ### 2. export with alias
 
-```vue
+```vue twoslash
 <script setup lang="ts">
+const foo = ''
+
 export { foo as foo1 }
 </script>
 ```
 
 ::: details Compiled Code
 
-```vue
+```vue twoslash
 <script setup lang="ts">
+const foo = 'foo'
+
 defineExpose({
   foo1: foo,
 })
@@ -87,16 +92,35 @@ defineExpose({
 
 ### 3. export from other file
 
-```vue
+::: code-group
+
+```vue [App.vue] twoslash
 <script setup lang="ts">
+// #region export-file
+const foo = 'foo'
+type Foo = string
+
+export { type Foo, foo }
+// #endregion export-file
+// ---cut---
+// @noErrors
 export { foo, type Foo, foo as bar } from './types'
 </script>
 ```
 
+<<< ./export-expose.md#export-file{ts} [types.ts]
+
+:::
+
 ::: details Compiled Code
 
-```vue
+```vue twoslash
 <script setup lang="ts">
+const __MACROS_expose_0 = 'foo'
+const __MACROS_expose_1 = 'foo'
+type Foo = string
+// ---cut---
+// @noErrors
 import {
   type Foo,
   foo as __MACROS_expose_0,
@@ -113,16 +137,32 @@ defineExpose({
 
 ### 4. namespace export
 
-```vue
+::: code-group
+
+```vue [App.vue] twoslash
 <script setup lang="ts">
+const foo = { foo: 'foo' }
+// ---cut---
+// @noErrors
 export * as foo from './types'
 </script>
 ```
 
+```ts [types.ts]
+export const foo = 'foo'
+```
+
+:::
+
 ::: details Compiled Code
 
-```vue
+```vue twoslash
 <script setup lang="ts">
+const __MACROS_expose_0 = {
+  foo: 'foo',
+}
+// ---cut---
+// @noErrors
 import * as __MACROS_expose_0 from './types'
 defineExpose({
   foo: __MACROS_expose_0,

docs/features/export-props.md

@@ -15,7 +15,7 @@
 
 Using export syntax to declare props.
 
-```vue
+```vue twoslash
 <script setup lang="ts">
 export let foo: string
 export const bar: number = 1 // with default value

docs/features/hoist-static.md

@@ -14,7 +14,7 @@ For Vue >= 3.3, this feature will be turned off by default.
 
 ## Basic Usage
 
-```vue
+```vue twoslash
 <script setup lang="ts">
 const name = 'AppFoo'
 defineOptions({
@@ -38,8 +38,10 @@ export default {
 
 ## Magic Comments
 
-```vue
+```vue twoslash
 <script setup lang="ts">
+const fn = () => 'AppFoo'
+
 // A value that's even not a constant
 const name = /* hoist-static */ fn()
 defineOptions({