Astro и MDX

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

Установка и настройка

Для работы с MDX в Astro необходимо установить соответствующий интеграционный пакет:

npm install @astrojs/mdx

После установки требуется добавить интеграцию в astro.config.mjs:

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [mdx()],
});

Поддержка MDX включает файлы с расширением .mdx. Astro автоматически обрабатывает такие файлы как страницы или компоненты в зависимости от расположения в проекте.

Структура MDX-файла

MDX-файл начинается с фронтматтер-объекта YAML, который используется для метаданных страницы:

---
title: "Пример использования MDX"
date: "2026-03-23"
---

# Заголовок страницы

Это **текст** с разметкой Markdown.

<Alert type="warning">
  Это компонент React внутри MDX.
</Alert>
  • --- обозначает фронтматтер, который может содержать произвольные ключи.
  • Разметка Markdown поддерживается полностью: заголовки, списки, таблицы, цитаты.
  • JSX-компоненты вставляются напрямую в тело документа, что позволяет интегрировать интерактивные элементы.

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

Любой React-компонент можно импортировать в MDX и использовать как обычный JSX:

import Button from '../components/Button.jsx';

<Button text="Нажми меня" onCl ick={() => alert('Привет!')} />

Компоненты могут принимать любые props, управлять состоянием, обрабатывать события. MDX позволяет легко комбинировать статический контент с динамическими элементами.

Оптимизация загрузки

Astro поддерживает частичную гидратацию (Partial Hydration), что позволяет загружать только необходимые компоненты на клиенте. Для MDX это особенно полезно:

<Button client:load text="Кнопка с загрузкой на клиенте" />
<Button client:visible text="Загружается при видимости" />
<Button client:idle text="Загружается в простое" />
  • client:load – компонент загружается сразу после загрузки страницы.
  • client:visible – загружается, когда компонент виден пользователю.
  • client:idle – загружается, когда браузер не занят другими задачами.

Импорт контента и организация

MDX-файлы могут использоваться как страницы или как контентные блоки для других компонентов:

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

<MyPost />

Структура проекта обычно организуется следующим образом:

src/
 ├─ pages/
 │   └─ index.mdx
 ├─ components/
 │   └─ Button.jsx
 └─ content/
     └─ post.mdx

Такой подход обеспечивает удобное разделение контента и логики приложения.

Работа с фронтматтером

Astro автоматически предоставляет данные фронтматтера как объект props в MDX:

---
title: "Фронтматтер пример"
---

<h1>{frontmatter.title}</h1>

Можно использовать любые поля фронтматтера для динамического построения контента, генерации метаданных или SEO-тегов.

Расширенные возможности

  • MDX в сочетании с TailwindCSS: можно использовать классы Tailwind прямо в JSX и Markdown-разметке.
  • Интеграция с внешними библиотеками: Astro позволяет использовать любые npm-пакеты внутри компонентов MDX.
  • Серверный рендеринг: все MDX-файлы рендерятся на стороне сервера, что повышает производительность и SEO-оптимизацию.

Особенности синтаксиса

  1. Экранирование Markdown внутри JSX – для использования символов Markdown внутри JSX необходимо использовать фигурные скобки и строковые литералы.
  2. Использование mdx pragma – для продвинутых случаев можно импортировать функции MDX напрямую для программного создания контента.
  3. Композиция контента – MDX позволяет объединять несколько файлов через импорты, что облегчает модульное построение документации или блога.

Примеры практического применения

  • Документация компонентов: каждый компонент сопровождается MDX-страницей с примерами и описанием props.
  • Блоги и статьи: комбинация Markdown и React-компонентов позволяет вставлять интерактивные виджеты и графики прямо в текст.
  • Справочные системы и учебники: интерактивные примеры кода в документации, которые можно сразу тестировать на клиенте.

MDX в связке с Astro обеспечивает гибкую и масштабируемую архитектуру для построения контента, сочетающего статическую разметку и динамическую функциональность компонентов.

Оглавление