Блоки кода

Rspress использует Shiki для подсветки синтаксиса на этапе компиляции, что обеспечивает лучшую производительность во время выполнения.

При использовании блоков кода на нескольких языках соответствующий язык автоматически определяется на этапе компиляции, а размер бандла во время выполнения не увеличивается. Список поддерживаемых языков программирования смотрите в списке языков, поддерживаемых Shiki.

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

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

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

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

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

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

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

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

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

src/components/HelloCodeBlockTitle.tsx

const HelloCodeBlockTitle = props => {
  return <h1>Блок кода с заголовком</h1>;
};

Блок кода из файла

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

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

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

foo.mdx

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

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

import { useState } from 'react';

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

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

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

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

```

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

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

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

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

```

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

Совет

При использовании блоков кода из внешних файлов их часто комбинируют с соглашениями о маршрутах. Называйте такие файлы с подчёркиванием в начале — _.

Подсветка отдельных строк

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

Code

rspress.config.ts

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

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

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

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

highlight.ts

console.log('Подсвечено'); 
console.log('Не подсвечено');
console.log('Подсвечено');
console.log('Подсвечено');

Подсветка строк через meta-информацию

Предупреждение

При использовании meta-информации для подсветки строк помните, что автоформаттеры и другие инструменты могут менять нумерацию строк. Для лучшей поддержки и удобства рекомендуется использовать подсветку через специальные комментарии.

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

Code

rspress.config.ts

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

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

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

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

console.log('Подсвечено');
console.log('Не подсвечено');
console.log('Подсвечено');
console.log('Подсвечено');

Нумерация строк

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

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

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

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

Вы также можете включить нумерацию строк глобально, указав опцию showLineNumbers в конфигурации:

rspress.config.ts

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

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

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

Перенос длинных строк

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

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

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

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

Вы также можете включить перенос длинных строк глобально, указав опцию defaultWrapCode в конфигурации:

rspress.config.ts

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

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

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

Высота блока кода

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

fold: сворачиваемый блок кода с кнопкой разворачивания. Высота по умолчанию 300px.
height=X: фиксированная высота с вертикальной полосой прокрутки. Если используется вместе с fold, блок кода будет сворачиваться до указанной высоты.
Без мета-атрибутов: полностью развёрнут по умолчанию. Вы можете изменить это глобально через markdown.defaultCodeOverflow.

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

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

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

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

fold-demo.tsx

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

Совет

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

Прокрутка

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

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

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

scroll-demo.tsx

const lines = Array.from({ length: 20 }, (_, index) => `Строка ${index + 1}`);

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

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

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

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

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

example.ts

const longLine =
  'Этот блок кода имеет нумерацию строк, перенос длинных строк и заголовок';

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

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

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

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

Трансформеры Shiki

Rspress использует Shiki для подсветки кода на этапе компиляции, что даёт широкие возможности по кастомизации блоков кода.

Вы можете подключать собственные трансформеры Shiki через опцию markdown.shiki.transformers — это позволяет получать более богатые эффекты в блоках кода.

Помимо уже упомянутого выше transformerNotationHighlight, Rspress по умолчанию включает следующие трансформеры из пакета @shikijs/transformers:

transformerNotationDiff

Syntax

rspress.config.ts

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

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

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

console.log('удалено'); 
console.log('добавлено'); 
console.log('без изменений');

transformerNotationErrorLevel

Syntax

rspress.config.ts

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

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

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

console.log('Без ошибок и предупреждений');
console.error('Ошибка'); 
console.warn('Предупреждение');

transformerNotationFocus

Syntax

rspress.config.ts

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

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

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

console.log('Без фокуса');
console.log('С фокусом'); 
console.log('Без фокуса');

Twoslash

Twoslash — это формат разметки для кода на TypeScript, который позволяет создавать полностью автономные примеры кода, автоматически дополняя их информацией о типах и подсказками от компилятора TypeScript. Он широко используется на официальном сайте TypeScript.

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

// @noErrorValidation
const str: string = 1;

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

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

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

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

highlight.ts

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

Предупреждение

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

#Блоки кода

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

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

#Блок кода из файла

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

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

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

#Подсветка отдельных строк

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

#Нумерация строк

#Перенос длинных строк

#Высота блока кода

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

#Прокрутка

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

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

#Трансформеры Shiki

#transformerNotationDiff

#transformerNotationErrorLevel

#transformerNotationFocus

#Twoslash

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

Блоки кода

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

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

Блок кода из файла

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

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

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

Подсветка отдельных строк

Подсветка строк через meta-информацию

Нумерация строк

Перенос длинных строк

Высота блока кода

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

Прокрутка

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

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

Трансформеры Shiki

transformerNotationDiff

transformerNotationErrorLevel

transformerNotationFocus

Twoslash

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