> For AI agents: the complete documentation index is available at /rspress-russian/llms.txt, the full documentation bundle is available at /rspress-russian/llms-full.txt.

# Блоки кода

Rspress использует [Shiki](https://shiki.style) для подсветки синтаксиса на этапе компиляции, что обеспечивает лучшую производительность во время выполнения.

При использовании блоков кода на нескольких языках соответствующий язык автоматически определяется на этапе компиляции, а размер бандла во время выполнения не увеличивается. Список поддерживаемых языков программирования смотрите в [списке языков, поддерживаемых Shiki](https://shiki.style/languages).

## Базовое использование

Вы можете использовать синтаксис \`\`\` для создания блоков кода. Например:

````mdx
```js
console.log('Привет, мир');
```
````

Это отображается как:

```js
console.log('Привет, мир');
```

## Заголовок блока кода

Вы можете добавить заголовок к блоку кода с помощью атрибута `title="..."`.

````mdx
```jsx title="src/components/HelloCodeBlockTitle.tsx"
const HelloCodeBlockTitle = props => {
  return <h1>Блок кода с заголовком</h1>;
};
```
````

Это отображается как:

```jsx title="src/components/HelloCodeBlockTitle.tsx"
const HelloCodeBlockTitle = props => {
  return <h1>Блок кода с заголовком</h1>;
};
```

## Блок кода из файла \{#file-code-block}

Вы можете использовать атрибут `file="./path/to/file"` без написания содержимого блока кода — это позволит подгрузить содержимое из внешнего файла.

### Относительные пути

Используйте относительные пути, начинающиеся с `./` или `../`, чтобы ссылаться на файлы относительно текущего MDX-файла:


**foo.mdx**

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

```
````


**_tsx-component.tsx**

```tsx file="./_tsx-component.tsx"
import { useState } from 'react';

export default () => {
  const [count, setCount] = useState(0);
  return (
    <p>
      Это компонент из tsx{' '}
      <button onClick={() => setCount(count => count + 1)}>{count}</button>
    </p>
  );
};

```


Это отображается как:

```tsx file="./_tsx-component.tsx"
import { useState } from 'react';

export default () => {
  const [count, setCount] = useState(0);
  return (
    <p>
      Это компонент из tsx{' '}
      <button onClick={() => setCount(count => count + 1)}>{count}</button>
    </p>
  );
};

```

### Абсолютные пути с префиксом `/`

Используйте префикс `/` для ссылки на файлы с помощью абсолютных путей относительно директории docs. Это полезно, когда нужно ссылаться на общие файлы кода из разных мест документации:

````mdx
```tsx file="/components/Button.tsx"

```
````

Например, если ваша директория docs находится в `/project/docs`, то `/components/Button.tsx` будет указывать на `/project/docs/components/Button.tsx`.

### Абсолютные пути с префиксом `<root>/`

Используйте префикс `<root>/`, чтобы ссылаться на файлы по абсолютному пути относительно корневой директории проекта. Это удобно, когда нужно обращаться к общим файлам кода из разных мест в документации:

````mdx
```tsx file="<root>/src/components/Button.tsx"

```
````

Например, если корень вашего проекта — `/project`, то путь `<root>/src/components/Button.tsx` будет указывать на файл, расположенный по адресу `/project/src/components/Button.tsx`.

:::tip

При использовании блоков кода из внешних файлов их часто комбинируют с [соглашениями о маршрутах](/rspress-russian/guide/use-mdx/components.md#routing-convention). Называйте такие файлы с подчёркиванием в начале — `_`.

:::

## Подсветка отдельных строк \{#notation-line-highlight}

Вы можете подсвечивать отдельные строки кода с помощью [трансформеров Shiki](#shiki-transformers) и специального трансформера `transformerNotationHighlight`, а также комментариев вида `// [!code highlight]`:


**Code**

````mdx
```ts
console.log('Подсвечено'); // [\!code highlight]
console.log('Не подсвечено');
// [\!code highlight:2]
console.log('Подсвечено');
console.log('Подсвечено');
```
````


**rspress.config.ts**

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

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


Это отображается как:

```ts title="highlight.ts"
console.log('Подсвечено'); // [!code highlight]
console.log('Не подсвечено');
// [!code highlight:2]
console.log('Подсвечено');
console.log('Подсвечено');
```

## Подсветка строк через meta-информацию \{#meta-line-highlight}

:::warning Предупреждение
При использовании meta-информации для подсветки строк помните, что автоформаттеры и другие инструменты могут менять нумерацию строк. Для лучшей поддержки и удобства рекомендуется использовать [подсветку через специальные комментарии](#notation-line-highlight).
:::

Вы можете подсвечивать строки кода с помощью трансформера `transformerCompatibleMetaHighlight` из пакета `@rspress/core/shiki-transformers` и meta-информации в заголовке блока кода.


**Code**

````mdx
```ts {1,3-4}
console.log('Подсвечено');
console.log('Не подсвечено');
console.log('Подсвечено');
console.log('Подсвечено');
```
````


**rspress.config.ts**

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

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


Это отображается как:

```ts {1,3-4}
console.log('Подсвечено');
console.log('Не подсвечено');
console.log('Подсвечено');
console.log('Подсвечено');
```

## Нумерация строк \{#show-code-line-numbers}

Вы можете включить отображение номеров строк для отдельных блоков кода с помощью мета-атрибута `lineNumbers`:

````mdx
```ts lineNumbers
function hello() {
  console.log('Для этого блока включена нумерация строк');
}
```
````

Это отображается как:

```ts lineNumbers
function hello() {
  console.log('Для этого блока включена нумерация строк');
}
```

Вы также можете включить нумерацию строк глобально, указав опцию [`showLineNumbers`](/rspress-russian/api/config/config-build.md#markdownshowlinenumbers) в конфигурации:

```ts title="rspress.config.ts"
export default {
  // ...
  markdown: {
    showLineNumbers: true,
  },
};
```

Когда опция `showLineNumbers` включена глобально, все блоки кода по умолчанию отображают номера строк. Вы можете отключить номера строк для конкретного блока кода, используя `lineNumbers=false`:

````mdx
```ts lineNumbers=false
function hello() {
  console.log('Нумерация строк отключена для данного блока');
}
```
````

## Перенос длинных строк \{#wrap-code}

Вы можете включить перенос длинных строк в отдельных блоках кода с помощью мета-атрибута `wrapCode`:


````mdx
```ts wrapCode
const longLine = 'Это очень длинная строка кода, которая будет переноситься по словам, когда указан мета-атрибут wrapCode';
```
````

Это отображается как:


```ts wrapCode
const longLine = 'Это очень длинная строка кода, которая будет переноситься по словам, когда указан мета-атрибут wrapCode';
```

Вы также можете включить перенос длинных строк глобально, указав опцию [`defaultWrapCode`](/rspress-russian/api/config/config-build.md#markdowndefaultwrapcode) в конфигурации:

```ts title="rspress.config.ts"
export default {
  // ...
  markdown: {
    defaultWrapCode: true,
  },
};
```

Когда опция `defaultWrapCode` включена глобально, все блоки кода по умолчанию будут переносить длинные строки. Вы можете отключить перенос кода для конкретного блока кода, используя `wrapCode=false`:


````mdx
```ts wrapCode=false
const longLine = 'Этот блок кода не будет переноситься, даже если опция `defaultWrapCode` включена глобально';
```
````

## Высота блока кода \{#code-block-height}

Вы можете управлять поведением высоты блоков кода, используя мета-атрибуты `height` и `fold`. Есть три варианта:

- **`fold`**: сворачиваемый блок кода с кнопкой разворачивания. Высота по умолчанию 300px.
- **`height=X`**: фиксированная высота с вертикальной полосой прокрутки. Если используется вместе с `fold`, блок кода будет сворачиваться до указанной высоты.
- **Без мета-атрибутов**: полностью развёрнут по умолчанию. Вы можете изменить это глобально через [`markdown.defaultCodeOverflow`](/rspress-russian/api/config/config-build.md#markdowndefaultcodeoverflow).

### Сворачивание

Используйте атрибут `fold` для включения функциональности разворачивания/сворачивания. Вы также можете настроить высоту свёрнутого блока через атрибут `height` (в пикселях, по умолчанию 300):

````mdx
```tsx fold height="350"
// Поместите сюда более длинный код, чтобы появилось сворачивание/разворачивание
```
````

Это отображается как:

```jsx title="fold-demo.tsx" fold height="350"
import { useState } from 'react';

export default () => {
  const [count, setCount] = useState(0);
  return (
    <div>
      <div>Строка 1</div>
      <div>Строка 2</div>
      <div>Строка 3</div>
      <div>Строка 4</div>
      <div>Строка 5</div>
      <div>Строка 6</div>
      <div>Строка 7</div>
      <div>Строка 8</div>
      <div>Строка 9</div>
      <div>Строка 10</div>
      <div>Строка 11</div>
      <div>Строка 12</div>
      <div>Строка 13</div>
      <div>Строка 14</div>
      <div>Строка 15</div>
      <div>Строка 16</div>
      <div>Строка 17</div>
      <div>Строка 18</div>
      <div>Строка 19</div>
      <div>Строка 20</div>
      <div>{count}</div>
      <button onClick={() => setCount(c => c + 1)}>{count}</button>
    </div>
  );
};
```

:::tip
Кнопка разворачивания/сворачивания не будет отображаться, если фактическая высота содержимого меньше `height`.
:::

### Прокрутка

Используйте атрибут `height` отдельно (без `fold`), чтобы задать фиксированную высоту с вертикальной полосой прокрутки:

````mdx
```tsx height="200"
// Поместите сюда более длинный код, чтобы появилась прокрутка
```
````

Это отображается как:

```tsx title="scroll-demo.tsx" height="200"
const lines = Array.from({ length: 20 }, (_, index) => `Строка ${index + 1}`);

export default function ScrollDemo() {
  return (
    <div>
      {lines.map(line => (
        <div key={line}>{line}</div>
      ))}
    </div>
  );
}
```

## Комбинирование мета-атрибутов

Вы можете одновременно использовать несколько мета-атрибутов:

````mdx
```ts lineNumbers wrapCode title="example.ts"
const longLine =
  'Этот блок кода имеет нумерацию строк, перенос длинных строк и заголовок';
```
````

Это отображается как:

```ts lineNumbers wrapCode title="example.ts"
const longLine =
  'Этот блок кода имеет нумерацию строк, перенос длинных строк и заголовок';
```

## Блок кода с подсветкой различий

````mdx
```diff
function test() {
- console.log('удалено');
+ console.log('добавлено');
  console.log('без изменений');
}
```
````

Это отображается как:

```diff
function test() {
- console.log('удалено');
+ console.log('добавлено');
  console.log('без изменений');
}
```

## Трансформеры Shiki \{#shiki-transformers}

Rspress использует [Shiki](https://shiki.style) для подсветки кода на этапе компиляции, что даёт широкие возможности по кастомизации блоков кода.

Вы можете подключать собственные [трансформеры Shiki](https://shiki.style/guide/transformers.html) через опцию [`markdown.shiki.transformers`](/rspress-russian/api/config/config-build.md#markdownshiki) — это позволяет получать более богатые эффекты в блоках кода.

Помимо уже упомянутого выше [transformerNotationHighlight](#notation-line-highlight), Rspress по умолчанию включает следующие трансформеры из пакета [@shikijs/transformers](https://shiki.style/packages/transformers):

### transformerNotationDiff


**Syntax**

````mdx
```ts
console.log('удалено'); // [\!code --]
console.log('добавлено'); // [\!code ++]
console.log('без изменений');
```
````


**rspress.config.ts**

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


Это отображается как:

```ts
console.log('удалено'); // [!code --]
console.log('добавлено'); // [!code ++]
console.log('без изменений');
```

### transformerNotationErrorLevel


**Syntax**

````mdx
```ts
console.log('Без ошибок и предупреждений');
console.error('Ошибка'); // [\!code error]
console.warn('Предупреждение'); // [\!code warning]
```
````


**rspress.config.ts**

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


Это отображается как:

```ts
console.log('Без ошибок и предупреждений');
console.error('Ошибка'); // [!code error]
console.warn('Предупреждение'); // [!code warning]
```

### transformerNotationFocus


**Syntax**

````mdx
```ts
console.log('Без фокуса');
console.log('С фокусом'); // [\!code focus]
console.log('Без фокуса');
```
````


**rspress.config.ts**

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


Это отображается как:

```ts
console.log('Без фокуса');
console.log('С фокусом'); // [!code focus]
console.log('Без фокуса');
```

## Twoslash

> [Twoslash](https://twoslash.netlify.app/guide/) — это формат разметки для кода на TypeScript, который позволяет создавать полностью автономные примеры кода, автоматически дополняя их информацией о типах и подсказками от компилятора TypeScript. Он широко используется на официальном сайте TypeScript.

Rspress предоставляет плагин `@rspress/plugin-twoslash`, который включает поддержку Twoslash в Rspress. Подробности — в [документации @rspress/plugin-twoslash](/rspress-russian/plugin/official-plugins/twoslash.md).

```ts twoslash
// @noErrorValidation
const str: string = 1;
```

## Подсветка синтаксиса во время выполнения

Когда нужно динамически отображать блоки кода во время выполнения — например, в интерактивной документации или при подгрузке кода с сервера, — Rspress предоставляет компонент `CodeBlockRuntime`.

Пример использования:

```mdx title="foo.mdx"
import { CodeBlockRuntime } from '@rspress/core/theme';
import { transformerNotationHighlight } from '@shikijs/transformers';

<CodeBlockRuntime
  lang="ts"
  title="highlight.ts"
  code={`console.log('Подсвечено'); // [\!code highlight]
// [\!code highlight:1]
console.log('Подсвечено');
console.log('Не подсвечено');`}
  shikiOptions={{
    transformers: [transformerNotationHighlight()],
  }}
/>
```


```ts title=highlight.ts
console.log('Подсвечено'); // [!code highlight]
// [!code highlight:1]
console.log('Подсвечено');
console.log('Не подсвечено');
```

:::warning Предупреждение
Используйте `CodeBlockRuntime` только при необходимости. Он увеличивает размер runtime-бандла и не позволяет использовать преимущества подсветки кода на этапе сборки.
:::
