Статический хостинг

MDX — это расширение Markdown, которое позволяет встраивать JSX-компоненты непосредственно в текст. Это делает его мощным инструментом для создания интерактивной документации, блогов и образовательного контента в приложениях на React.

Синтаксис MDX

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

Пример:

# Заголовок

Это обычный текст Markdown.

<MyButton>Нажми меня</MyButton>

В данном примере <MyButton> — React-компонент, который будет корректно отрендерен в месте своего вызова.

Импорт и использование компонентов

В MDX можно импортировать компоненты из других файлов:

import Alert from './components/Alert';

<Alert type="warning">
  Важно! Это предупреждение.
</Alert>

MDX автоматически распознает импортированные компоненты и позволяет использовать их внутри документации или статьи так, как если бы это был обычный JSX.

Преобразование MDX в JavaScript

Для работы с MDX в приложении на React необходимо использовать библиотеки @mdx-js/mdx и @mdx-js/react. Основной процесс состоит из двух шагов:

  1. Компиляция MDX в JSX: MDX-файл преобразуется в JSX-код с помощью компилятора @mdx-js/mdx.
import { compile } from '@mdx-js/mdx';
import fs from 'fs';

const source = fs.readFileSync('./example.mdx', 'utf8');
const jsx = await compile(source, { outputFormat: 'function-body' });
console.log(String(jsx));
  1. Рендеринг с React: После компиляции можно использовать результат в React-компоненте через MDXProvider:
import { MDXProvider } from '@mdx-js/react';
import MDXContent from './example.mdx';

<MDXProvider components={{ Alert }}>
  <MDXContent />
</MDXProvider>

Использование кастомных компонентов

MDX позволяет переопределять стандартные HTML-теги и использовать свои компоненты для любого блока:

const components = {
  h1: (props) => <h1 style={{ color: 'tomato' }} {...props} />,
  p: (props) => <p className="custom-paragraph" {...props} />,
};

Передача объекта components в MDXProvider заменяет стандартные рендеры Markdown на кастомные.

Статический хостинг MDX-контента

MDX особенно эффективен в статических сайтах, таких как те, что создаются с Next.js, Gatsby или Astro. Процесс выглядит следующим образом:

  1. Компиляция MDX на этапе сборки Статические генераторы сайтов обрабатывают MDX-файлы в JSX и сразу создают готовые HTML-страницы. Это ускоряет загрузку и улучшает SEO.

  2. Импорт контента как модулей Вместо динамической загрузки MDX-файлов их можно импортировать как модули Jav * aScript:

import PostContent from '../content/post.mdx';

export default function PostPage() {
  return <PostContent />;
}
  1. Оптимизация изображений и медиа MDX совместим с компонентами для оптимизации изображений (next/image в Next.js) и интерактивных виджетов. Это позволяет включать медиа и визуализации без дополнительных скриптов на клиенте.

Преимущества MDX на статическом хостинге

  • Быстрая загрузка страниц: компиляция контента происходит заранее.
  • SEO-оптимизация: весь текст доступен поисковым ботам.
  • Безопасность: отсутствует необходимость в клиентском парсинге Markdown.
  • Гибкость компонентов: React-компоненты работают как нативные элементы в документе.

Практические рекомендации

  • Для крупных проектов стоит настроить систему автоматической генерации страниц из MDX-файлов.
  • Использование TypeScript с MDX помогает избежать ошибок при работе с компонентами и их пропсами.
  • Разделение контента и логики компонентов повышает читаемость и облегчает поддержку проекта.
  • Включение линтера для MDX (eslint-plugin-mdx) гарантирует единый стиль и предотвращает синтаксические ошибки.

Совместимость с современными фреймворками

  • Next.js: next-mdx-remote позволяет загружать MDX динамически и использовать статическую генерацию.
  • Gatsby: gatsby-plugin-mdx интегрируется с GraphQL для извлечения данных.
  • Astro: MDX поддерживается нативно, что позволяет строить гибридные сайты с Markdown-контентом и React-компонентами одновременно.

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

Оглавление