Skip to content

Code Snippets

Including code snippets in Markdown

Code Snippets in Vocs come in two forms:

We will show you both approaches below.

Virtual File Snippets

Create the code snippet

We will create a virtual file snippet called example.ts. We can define a virtual file in markdown using the filename="example.ts" meta tag.

example.md
```ts filename="example.ts"
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
```

Import the snippet

Next, we will import the snippet into our Markdown file using the // [!include ...] marker.

example.md
#### Create your Client
 
```ts filename="example.ts"
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
```
 
#### Use Actions
 
```ts
// [!include example.ts]
 
const blockNumber = await client.getBlockNumber() // [!code focus]
```

Output

The resulting output will look like this:

Create your Client

import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})

Use Actions

import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
 
const blockNumber = await client.getBlockNumber()

Physical File Snippets

Create the code snippet

We will create a physical file snippet called example.ts. Let's put this under a snippets/ directory in your codebase.

docs/snippets/example.ts
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})

Import the snippet

Next, we will import the snippet into our Markdown file using the // [!include ...] marker.

example.md
#### Create your Client
 
```ts
// [!include ~/snippets/example.ts]
```
 
#### Use Actions
 
```ts 
// [!include ~/snippets/example.ts]
 
const blockNumber = await client.getBlockNumber() // [!code focus]
```

Output

The resulting output will look like this:

Create your Client

import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})

Use Actions

import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
 
const blockNumber = await client.getBlockNumber()

Regions

You can also include a specific region of a code snippet by using the // [!region] and // [!endregion] markers.

docs/snippets/example.ts
// [!region import]
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
// [!endregion import]
 
// [!region setup]
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
// [!endregion setup]
 
// [!region usage]
const blockNumber = await client.getBlockNumber()
// [!endregion usage]

Then, we can include the regions in the Markdown with the // [!include] marker:

example.md
```ts
import { writeFileSync } from 'node:fs'
// [!include ~/snippets/example.ts:import]
 
// [!include ~/snippets/example.ts:setup]
 
// [!include ~/snippets/example.ts:usage]
 
writeFileSync('test.txt', blockNumber.toString())
```

Which will result in the snippet being rendered like this:

import { writeFileSync } from 'node:fs'
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
 
const blockNumber = await client.getBlockNumber()
 
writeFileSync('test.txt', blockNumber.toString())

Duplicate variable declarations

When writing snippets, you may run into a scenario where you want to define multiple regions that share the same variable name.

To avoid type errors, you can use the _$ suffix to discriminate the variable name.

The rendered snippet will still use the original variable name (ie. the name before the _$ suffix).

import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
 
const block_$1 = await client.getBlock() 
 
const block_$2 = await client.getBlock({ blockNumber: 42069n }) 
 
const block_$3 = await client.getBlock({ blockTag: 'latest' })

Find and Replace

You can use /(find)/(replace)/ syntax to find and replace text in the snippet.

example.md
```ts
import { writeFileSync } from 'node:fs'
// [!include ~/snippets/example.ts /viem/@viem\/core/ /mainnet/sepolia/]
 
writeFileSync('test.txt', blockNumber.toString())
```

Which will result in the snippet being rendered like this:

import { writeFileSync } from 'node:fs'
import { http, createPublicClient } from '@viem/core'
import { sepolia } from '@viem/core/chains'
 
const client = createPublicClient({
  chain: sepolia,
  transport: http(),
})
 
const blockNumber = await client.getBlockNumber()
 
writeFileSync('test.txt', blockNumber.toString())

Tip: Code Block Markers

We can also include markers like line highlight (// [!code hl]) in our code snippets.

docs/snippets/example.ts
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
 
const blockNumber = await client.getBlockNumber() // [!code hl]

Which will result in the snippet being rendered like this:

import { writeFileSync } from 'node:fs'
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
 
const blockNumber = await client.getBlockNumber() 
 
writeFileSync('test.txt', blockNumber.toString())

Tip: Twoslash

We can also include Twoslash markers in our code snippets.

docs/snippets/example.ts
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
 
const blockNumber = await client.getBlockNumber()
//    ^?

Which will result in the snippet being rendered like this:

import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
 
const 
const blockNumber: bigint
blockNumber = await client.getBlockNumber()

Tip: Twoslash + Virtual Files

We can also use virtual files with Twoslash code blocks.

Markdown
:::code-group
 
```ts twoslash [example.ts]
import { client } from './client.js'
 
const blockNumber = await client.getBlockNumber()
```
 
```ts twoslash [client.ts] filename="client.ts"
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
export const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
```
 
:::

Which will result in the snippet being rendered like this:

example.ts
import { client } from './client.js'
 
const blockNumber = await client.getBlockNumber()