3.5 KiB
| description | title |
|---|---|
| Include re-usable TypeScript blocks in your code examples. | Includes |
Includes
As your documentation grows, you may need a way of re-using code blocks to prevent code duplication. Shiki Twoslash provides a simple includes system.
Defining a re-usable block
Re-usable code blocks are defined by the twoslash language, followed by the include keyword and the reference name of your choice.
```twoslash include myBlock
type SomeString = string
```
Incremental steps
Shiki Twoslash also provide the ability to define incremental steps through the definition of re-usable blocks. This means whenever a new step is delimited down the code, it will also include previous steps. These are not groups.
- Incremental steps are delimited by
// - [name of the step] - They are named at the end of the actual code
```twoslash include myBlockWithSteps
type SomeString = string
// - base
type SomeUser = { name: string; mail?: SomeUserMail }
type SomeUserMail = { content: string; verified: boolean }
// - afterUserDefinitions
type SomeGroup = { name: string; members: SomeUser[] }
// - afterGroupDefinitions
```
Including a whole block
To include a re-usable block, add // @include: [block name] in your code block.
type SomeString = string
::: code-group
// @include: myBlock
const a: SomeString = 'string'
```twoslash include myBlock
type SomeString = string
```
```ts twoslash
// @include: myBlock
const a: SomeString = 'string'
```
:::
Including a block step
To include a re-usable block at a specific step, add // @include: [block name]-[step name] in your code block.
type SomeString = string
// - base
type SomeUser = { name: string; mail?: SomeUserMail }
type SomeUserMail = { content: string; verified: boolean }
// - afterUserDefinitions
type SomeGroup = { name: string; members: SomeUser[] }
// - afterGroupDefinitions
::: code-group
// @include: myBlockWithSteps-afterUserDefinitions
const mail: SomeUserMail = { content: 'some-email', verified: true }
```twoslash include myBlockWithSteps
type SomeString = string
// - base
type SomeUser = { name: string; mail?: SomeUserMail }
type SomeUserMail = { content: string; verified: boolean }
// - afterUserDefinitions
type SomeGroup = { name: string; members: SomeUser[] }
// - afterGroupDefinitions
```
```ts twoslash
// @include: myBlockWithSteps-afterUserDefinitions
const mail: SomeUserMail = { content: 'some-email', verified: true }
```
:::
Hiding re-used code
Re-using a lot of TypeScript code can easily bloat your documentation and obstruct the main point of your code block. You can hide re-used code to keep your code blocks clean and concise by cutting right after the @include statement.
::: code-group
// @include: myBlockWithSteps-afterUserDefinitions
// ---cut---
const mail: SomeUserMail = { content: 'some-email', verified: true }
```twoslash include myBlockWithSteps
type SomeString = string
// - base
type SomeUser = { name: string; mail?: SomeUserMail }
type SomeUserMail = { content: string; verified: boolean }
// - afterUserDefinitions
type SomeGroup = { name: string; members: SomeUser[] }
// - afterGroupDefinitions
```
```ts twoslash
// @include: myBlockWithSteps-afterUserDefinitions
// ---cut---
const mail: SomeUserMail = { content: 'some-email', verified: true }
```
:::