Toshiki's Note

Appearance

@andatoshiki/vitepress-plugin-shiki-twoslash ​

Author:Anda Toshiki
Updated:2 months ago
Words:437
Reading:2 min

Static code examples for VitePress using Shiki Twoslash — powered by the syntax engine of Visual Studio Code and the TypeScript compiler.

Overview ​

Try moving your cursor into the code block below:

ts
ts
// Removes 'readonly' attributes from a type's properties
type CreateMutable<Type> = {
    -readonly [Property in keyof Type]: Type[Property]
}
 
type LockedAccount = {
    readonly id: string
    readonly name: string
}
 
type UnlockedAccount = CreateMutable<LockedAccount>
ts
// Removes 'readonly' attributes from a type's properties
type CreateMutable<Type> = {
    -readonly [Property in keyof Type]: Type[Property]
}
 
type LockedAccount = {
    readonly id: string
    readonly name: string
}
 
type UnlockedAccount = CreateMutable<LockedAccount>

Pretty neat, right? To some extent, anything your editor can show you about code, Twoslash can show. For example, here is the real auto-complete for a VitePress config:

ts
ts
import { defineConfig } from 'vitepress'
 
export default defineConfig({
    ti,
      
  • title
  • titleTemplate
})
ts
import { defineConfig } from 'vitepress'
 
export default defineConfig({
    ti,
      
  • title
  • titleTemplate
})

The name Twoslash refers to specially formatted comments (e.g. // ^?) which can be used to set up your environment, like compiler flags or separate input files. It couldn't be easier to set up and start creating incredible code examples!

Install ​

Install @andatoshiki/vitepress-plugin-shiki-twoslash (requires vitepress@>=1.0.0-alpha.61).

bash
pnpm add @andatoshiki/vitepress-plugin-shiki-twoslash
pnpm add @andatoshiki/vitepress-plugin-shiki-twoslash
bash
npm i @andatoshiki/vitepress-plugin-shiki-twoslash
npm i @andatoshiki/vitepress-plugin-shiki-twoslash
bash
yarn add @andatoshiki/vitepress-plugin-shiki-twoslash
yarn add @andatoshiki/vitepress-plugin-shiki-twoslash

WARNING

Until shiki-twoslash uses the same version of shiki as VitePress, you must override the following packages' shiki versions for syntax highlighting to look the same.

json
{
    "pnpm": {
        "overrides": {
            "remark-shiki-twoslash>shiki": "^0.14.1",
            "shiki-twoslash>shiki": "^0.14.1"
        }
    }
}
{
    "pnpm": {
        "overrides": {
            "remark-shiki-twoslash>shiki": "^0.14.1",
            "shiki-twoslash>shiki": "^0.14.1"
        }
    }
}

Tracked in an upstream issue: https://github.com/shikijs/twoslash/issues/180

Configure ​

First, wrap your VitePress config file with the withTwoslash wrapper.

ts
ts
// .vitepress/config.[ext]
import { defineConfig } from 'vitepress'
import { withTwoslash } from '@andatoshiki/vitepress-plugin-shiki-twoslash'
 
export default withTwoslash(
    defineConfig({
        // Your VitePress config
    })
)
ts
// .vitepress/config.[ext]
import { defineConfig } from 'vitepress'
import { withTwoslash } from '@andatoshiki/vitepress-plugin-shiki-twoslash'
 
export default withTwoslash(
    defineConfig({
        // Your VitePress config
    })
)

Then, import @andatoshiki/vitepress-plugin-shiki-twoslash/styles.css into your theme.

ts
ts
// .vitepress/theme/index.ts
import defaultTheme from 'vitepress/theme'
import '@andatoshiki/vitepress-plugin-shiki-twoslash/styles.css'
 
export default defaultTheme
ts
// .vitepress/theme/index.ts
import defaultTheme from 'vitepress/theme'
import '@andatoshiki/vitepress-plugin-shiki-twoslash/styles.css'
 
export default defaultTheme

TIP

You can configure VitePress Twoslash using the twoslash property added to defineConfig.

Add Twoslash ​

Finally, add the twoslash attribute to markdown fenced code blocks.

md
```ts twoslash
// Removes 'readonly' attributes from a type's properties
type CreateMutable<Type> = {
    -readonly [Property in keyof Type]: Type[Property]
}

type LockedAccount = {
    readonly id: string
    readonly name: string
}

type UnlockedAccount = CreateMutable<LockedAccount>
//   ^?
```
```ts twoslash
// Removes 'readonly' attributes from a type's properties
type CreateMutable<Type> = {
    -readonly [Property in keyof Type]: Type[Property]
}

type LockedAccount = {
    readonly id: string
    readonly name: string
}

type UnlockedAccount = CreateMutable<LockedAccount>
//   ^?
```

And your code blocks will be twoslashified!

ts
ts
// Removes 'readonly' attributes from a type's properties
type CreateMutable<Type> = {
    -readonly [Property in keyof Type]: Type[Property]
}
 
type LockedAccount = {
    readonly id: string
    readonly name: string
}
 
type UnlockedAccount = CreateMutable<LockedAccount>
           
type UnlockedAccount = {
    id: string;
    name: string;
}
ts
// Removes 'readonly' attributes from a type's properties
type CreateMutable<Type> = {
    -readonly [Property in keyof Type]: Type[Property]
}
 
type LockedAccount = {
    readonly id: string
    readonly name: string
}
 
type UnlockedAccount = CreateMutable<LockedAccount>
           
type UnlockedAccount = {
    id: string;
    name: string;
}