#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"

```

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

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');
```

import { defineConfig } from '@rspress/core';
import { transformerNotationHighlight } from '@shikijs/transformers';

export default defineConfig({
  markdown: {
    shiki: {
      transformers: [transformerNotationHighlight()],
    },
  },
});

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');
```

import { defineConfig } from '@rspress/core';
import { transformerCompatibleMetaHighlight } from '@rspress/core/shiki-transformers';

export default defineConfig({
  markdown: {
    shiki: {
      transformers: [transformerCompatibleMetaHighlight()],
    },
  },
});

It will be rendered as:

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

#Show code line numbers

You can show line numbers for individual code blocks using the lineNumbers meta attribute:

```ts lineNumbers
function hello() {
  console.log('Line numbers enabled for this block');
}
```

It will be rendered as:

function hello() {
  console.log('Line numbers enabled for this block');
}

You can also enable line numbers globally by setting the showLineNumbers option in the config file:

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

When showLineNumbers is enabled globally, all code blocks will show line numbers by default.

#Wrap code

You can enable code wrapping for individual code blocks using the wrapCode meta attribute:

```ts wrapCode
const longLine =
  'This is a very long line of code that will wrap when the wrapCode meta attribute is present';
```

It will be rendered as:

const longLine =
  'This is a very long line of code that will wrap when the wrapCode meta attribute is present';

You can also enable code wrapping globally by setting the defaultWrapCode option in the config file:

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

When defaultWrapCode is enabled globally, all code blocks will wrap long lines by default.

#Combining meta attributes

You can combine multiple meta attributes together:

```ts lineNumbers wrapCode title="example.ts"
const longLine = 'This code block has line numbers, code wrapping, and a title';
```

It will be rendered as:

const longLine = 'This code block has line numbers, code wrapping, and a title';

#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');
```

import { defineConfig } from '@rspress/core';
import { transformerNotationDiff } from '@shikijs/transformers';
export default defineConfig({
  markdown: {
    shiki: {
      transformers: [transformerNotationDiff()],
    },
  },
});

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]
```

import { defineConfig } from '@rspress/core';
import { transformerNotationErrorLevel } from '@shikijs/transformers';
export default defineConfig({
  markdown: {
    shiki: {
      transformers: [transformerNotationErrorLevel()],
    },
  },
});

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');
```

import { defineConfig } from '@rspress/core';
import { transformerNotationFocus } from '@shikijs/transformers';
export default defineConfig({
  markdown: {
    shiki: {
      transformers: [transformerNotationFocus()],
    },
  },
});

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()],
  }}
/>