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
```
```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
```
```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.
ts
typeSomeString = stringconsta :SomeString = 'string'
ts
typeSomeString = stringconsta :SomeString = 'string'
```twoslash include myBlock
type SomeString = string
```
```ts twoslash
// @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.
ts
typeSomeString = stringtypeSomeUser = {name : string;SomeUserMail }typeSomeUserMail = {content : string;verified : boolean }constSomeUserMail = {content : 'some-email',verified : true }
ts
typeSomeString = stringtypeSomeUser = {name : string;SomeUserMail }typeSomeUserMail = {content : string;verified : boolean }constSomeUserMail = {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 }
```
```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.
ts
constSomeUserMail = {content : 'some-email',verified : true }
ts
constSomeUserMail = {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 }
```
```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 }
```