Skip to content

@andatoshiki/vitepress-plugin-shiki-twoslash

Author:Anda Toshiki
Updated:a day 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,
      
})
ts
import { defineConfig } from 'vitepress'
 
export default defineConfig({
ti,
      
})

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; }