#Code blocks

Rspress V2 uses Shiki for syntax highlighting at compile time, which means better runtime performance.

When using code blocks in multiple languages, the corresponding language is automatically detected at compile time, and the runtime bundle size does not increase. For supported programming languages, refer to the Shiki supported languages list.

#Basic usage

You can use the ``` syntax to create code blocks. For example:

```js
console.log('Hello World');
```

It will be rendered as:

console.log('Hello World');

#Code block title

You can use the title="..." attribute to add a title to a code block.

```jsx title="src/components/HelloCodeBlockTitle.tsx"
const HelloCodeBlockTitle = (props) => {
  return <h1>Hello CodeBlock Title</h1>;
};
```

It will be rendered as:

const HelloCodeBlockTitle = (props) => {
  return <h1>Hello CodeBlock Title</h1>;
};

#External file code block

You can use the file="./path/to/file" attribute without writing any code block content to reference the text from an external file.

```tsx file="./_tsx-component.tsx"

```

It will be rendered as:

import { useState } from 'react';

export default () => {
  const [count, setCount] = useState(0);
  return (
    <p>
      This is a component from tsx{' '}
      <button onClick={() => setCount(count => count + 1)}>{count}</button>
    </p>
  );
};

#Notation line highlight

You can use Shiki transformers with the transformerNotationHighlight and // [!code highlight] comments to highlight code lines.

```ts
console.log('Highlighted'); // [\!code highlight]
console.log('Not highlighted');
// [\!code highlight:2]
console.log('Highlighted');
console.log('Highlighted');
```

It will be rendered as:

console.log('Highlighted'); 
console.log('Not highlighted');
console.log('Highlighted');
console.log('Highlighted');

#Meta line highlight

You can use @rspress/core/shiki-transformers with transformerCompatibleMetaHighlight and meta info comments to highlight code lines.

```ts {1,3-4}
console.log('Highlighted');
console.log('Not highlighted');
console.log('Highlighted');
console.log('Highlighted');
```

It will be rendered as:

console.log('Highlighted');
console.log('Not highlighted');
console.log('Highlighted');
console.log('Highlighted');

#Show code line numbers

If you want to show code line numbers, you can enable the showLineNumbers option in the config file:

export default {
  // ...
  markdown: {
    showLineNumbers: true,
  },
};

#Wrap code

If you want to enable long code wrapping by default, you can enable the defaultWrapCode option in the config file:

export default {
  // ...
  markdown: {
    defaultWrapCode: true,
  },
};

#Diff code block

```diff
function test() {
- console.log('deleted');
+ console.log('added');
  console.log('unchanged');
}
```

It will be rendered as:

function test() {
- console.log('deleted');
+ console.log('added');
  console.log('unchanged');
}

#Shiki transformers

Rspress V2 uses Shiki for compile-time code highlighting, providing flexible code block capabilities.

You can add custom shiki transformers via markdown.shiki.transformers for richer code block effects.

In addition to the transformerNotationHighlight mentioned above, Rspress defaults to supporting the following transformers from @shikijs/transformers.

#transformerNotationDiff

```ts
console.log('deleted'); // [\!code --]
console.log('added'); // [\!code ++]
console.log('unchanged');
```

It will be rendered as:

console.log('deleted'); 
console.log('added'); 
console.log('unchanged');

#transformerNotationErrorLevel

```ts
console.log('No errors or warnings');
console.error('Error'); // [\!code error]
console.warn('Warning'); // [\!code warning]
```

It will be rendered as:

console.log('No errors or warnings');
console.error('Error'); 
console.warn('Warning'); 

#transformerNotationFocus

```ts
console.log('Not focused');
console.log('Focused'); // [\!code focus]
console.log('Not focused');
```

It will be rendered as:

console.log('Not focused');
console.log('Focused'); 
console.log('Not focused');

#Twoslash

Twoslash is a markup format for TypeScript code, suitable for creating self-contained code samples and letting the TypeScript compiler automatically supplement type information and hints. It is widely used on the official TypeScript website.

Rspress provides the @rspress/core/plugin-twoslash plugin, which enables Twoslash features in Rspress. See @rspress/plugin-twoslash documentation for details.

const str: string = 1;
Type 'number' is not assignable to type 'string'.

#Runtime syntax highlighting

When you need to render code blocks dynamically at runtime, such as in interactive docs or fetching code remotely, Rspress provides the CodeBlockRuntime component.

Here is an example:

import { CodeBlockRuntime } from '@theme';
import { transformerNotationHighlight } from '@shikijs/transformers';

<CodeBlockRuntime
  lang="ts"
  title="highlight.ts"
  code={`console.log('Highlighted'); // [\!code highlight]
// [\!code highlight:1]
console.log('Highlighted');
console.log('Not highlighted');`}
  shikiOptions={{
    transformers: [transformerNotationHighlight()],
  }}
/>