MDX

MDX — это Markdown, в котором можно использовать компоненты и выражения JavaScript. Обычный текст пишется как в Markdown, а в нужном месте вставляется компонент — например, рамка с предупреждением или кнопка. Поддержку MDX в Astro добавляет официальная интеграция.

Подключение

Интеграция — пакет, который расширяет возможности Astro. Её устанавливают командой astro add:

npx astro add mdx

Команда установит пакет @astrojs/mdx и сама допишет его в astro.config.mjs:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
 
export default defineConfig({
  integrations: [mdx()],
});

Перезапустите сервер разработки: после изменения настроек он подхватывает их не всегда.

Компонент внутри текста

Создайте компонент рамки src/components/Note.astro:

<aside class="note">
  <slot />
</aside>
 
<style>
  .note {
    padding: 1rem;
    background: #fff8e1;
    border-left: 4px solid #f5b400;
  }
</style>

Теперь создайте страницу src/pages/uses.mdx:

---
layout: ../layouts/MarkdownLayout.astro
title: Чем я пользуюсь
---
import Note from '../components/Note.astro';
 
Редактор — **VS Code**, браузер — Firefox.
 
<Note>
  Список обновлён весной 2025 года.
</Note>

Откройте /uses — текст оформлен как обычный Markdown, а между абзацами стоит жёлтая рамка. Компонент импортируют сразу после фронтматтера и пишут как тег.

Выражения

В MDX работают фигурные скобки. Переменная frontmatter содержит данные из фронтматтера файла:

---
layout: ../layouts/MarkdownLayout.astro
title: Чем я пользуюсь
---
 
Страница «{frontmatter.title}» появилась в 2025 году.
 
В списке {2 + 1} программы.

Под заголовком из макета появятся две строки: в первую подставится название «Чем я пользуюсь» из фронтматтера, во второй вместо {2 + 1} будет число 3.

Markdown или MDX

Оба формата работают и как страницы в src/pages/, и как записи коллекций содержимого.

Частая ошибка

В MDX символы {, } и < имеют особый смысл. Фраза вроде «если a < b» или фигурная скобка в обычном тексте ломает сборку с ошибкой разбора. Такие символы заключайте в обратные кавычки (как код) или используйте для этого текста обычный .md.