Блоки кода и подсветка синтаксиса

Создание блоков кода

В MDX блоки кода создаются по принципу стандартного Markdown с использованием тройных обратных кавычек ```. Важным аспектом является указание языка программирования сразу после первых тройных кавычек для правильной подсветки синтаксиса.

Пример:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}

В этом примере `javascript` задаёт язык, по которому будет выполнена подсветка синтаксиса. MDX позволяет использовать любые поддерживаемые Markdown-библиотеки, такие как `remark` и `rehype`, для обработки блоков кода и их интеграции с React-компонентами.

#### Интеграция с React-компонентами

MDX позволяет заменять стандартные блоки кода на кастомные React-компоненты для расширенной функциональности, например, для интерактивной подсветки или копирования в буфер обмена.  

Пример:

```mdx
import CodeBlock from './CodeBlock'

<CodeBlock language="javascript">
{`
function sum(a, b) {
  return a + b;
}
`}
</CodeBlock>

В этом подходе компонент CodeBlock может использовать библиотеку подсветки синтаксиса, например, Prism.js или Highlight.js, и предоставлять дополнительные возможности: темы, линтеры, подсветку ошибок и выделение отдельных строк.

Подсветка синтаксиса с Prism

Prism.js — одна из самых популярных библиотек для подсветки синтаксиса в MDX. Для интеграции требуется импортировать необходимые темы и языки:

import Prism from 'prismjs';
import 'prismjs/themes/prism-tomorrow.css';
import 'prismjs/components/prism-javascript';
import 'prismjs/components/prism-css';

После этого можно создать компонент CodeBlock, который принимает language и children и обрабатывает их через Prism.highlight:

function CodeBlock({ language, children }) {
  const html = Prism.highlight(children, Prism.languages[language], language);
  return <pre className={`language-${language}`} dangerouslySetInnerHTML={{ __html: html }} />;
}

Такой компонент позволяет динамически подсвечивать любые блоки кода в MDX, сохраняя их форматирование и поддержку различных языков программирования.

Поддержка дополнительных возможностей

  1. Выделение строк — часто необходимо подчеркнуть или выделить ключевые части кода. В MDX это реализуется через специальные пропсы в компоненте:
<CodeBlock language="javascript" highlightLines={[2,3]}>
{`
function add(a, b) {
  return a + b;
}
`}
</CodeBlock>
  1. Копирование в буфер — добавление кнопки «Copy» улучшает UX документации и туториалов:
function CopyButton({ text }) {
  const handleCopy = () => navigator.clipboard.writeText(text);
  return <button onCl ick={handleCopy}>Copy</button>;
}
  1. Тема подсветки — Prism и другие библиотеки позволяют динамически менять темы через CSS или пропсы. Это особенно удобно при использовании светлой и тёмной темы на сайте.

Обработка блоков кода на стороне MDX

MDX предоставляет возможность обрабатывать блоки кода на этапе компиляции через remark и rehype. Примеры популярных плагинов:

  • remark-prism — автоматическая подсветка с поддержкой тем.
  • rehype-highlight — преобразует блоки кода в HTML с нужными классами для CSS-подсветки.
  • remark-code-titles — добавляет заголовки к блокам кода для лучшей читаемости.

Конфигурация в next-mdx-remote или @mdx-js/loader может выглядеть так:

import rehypeHighlight from 'rehype-highlight';
import remarkGfm from 'remark-gfm';

const mdxOptions = {
  remarkPlugins: [remarkGfm],
  rehypePlugins: [rehypeHighlight]
};

Важные практики

  • Указание языка обязательно — это позволяет правильно подсветить синтаксис и избегает дефолтного форматирования.
  • Использование компонентов для блоков кода — расширяет функциональность и интеграцию с интерактивными элементами.
  • Разделение логики и разметки — блок кода в MDX лучше оставлять чистым текстом, а все манипуляции с подсветкой и взаимодействием выносить в React-компоненты.
  • Совместимость с Markdown-плагинами — большинство MDX-библиотек поддерживают плагины для расширенной обработки кода, включая автоформатирование и линтинг.

Выводы по использованию

MDX предоставляет гибкий и мощный инструмент для работы с блоками кода: от простого Markdown до сложных React-компонентов с подсветкой и интерактивными функциями. Правильная структура, использование языковых указаний и интеграция с библиотеками подсветки делают документацию и учебные материалы на MDX удобными, наглядными и профессиональными.

Оглавление