Что такое MDX-файлы и почему это стандарт контента

Долгое время у создателей контента было только два пути. Либо писать тексты в визуальных WYSIWYG-редакторах, генерирующих грязный, нечитаемый HTML. Либо использовать Markdown — красивый минималистичный формат, который отлично подходил для текста, но был бесполезен, если в статью нужно вставить интерактивный элемент вроде работающего графика или калькулятора.

Формат MDX решил эту проблему, объединив простоту Markdown с мощью компонентных фреймворков (JSX). В 2026 году это абсолютный стандарт для технической документации, блогов разработчиков и современных медиа-изданий.

Эволюция форматов: от HTML к MDX

Чтобы понять ценность MDX, пройдем путь эволюции форматов разметки:

HTML (1993): Полная мощь, полный хаос для автора. Написать простую статью означало окружить каждый абзац тегами <p>, каждую ссылку тегами <a href="...">. Отличный язык для браузеров, ужасный для людей.

Markdown (2004): Джон Грубер решил: разметка должна читаться как обычный текст. Звездочки для жирного, решетки для ## Заголовков, скобки для [ссылок](url). Markdown компилируется в HTML и стал стандартом для миллионов блогов и GitHub README.

MDX (2018): Логичный следующий шаг. MDX — это надмножество Markdown. Вы пишете тот же самый привычный текст, но с одной суперспособностью: внутри контента можно использовать интерактивные JSX-компоненты.

Если Markdown — это текст с базовым форматированием, то MDX — это текст с программируемыми интерактивными блоками.

Синтаксис MDX: Полный разбор

Файл MDX состоит из трех ключевых частей: Frontmatter, обычного Markdown-текста и JSX-компонентов.

Часть 1: Frontmatter (YAML-шапка)

Каждый MDX-файл начинается с блока метаданных в формате YAML между тройными дефисами. Именно здесь хранится вся «мета-информация» о статье:

---
title: 'Как работает сложный процент'
description: 'Объясняем принцип сложных процентов с живым калькулятором'
date: 2026-04-13
author: 'Иван Иванов'
tags: ['Финансы', 'Инвестиции']
cover: '../../assets/covers/compound-interest.webp'
coverAlt: 'График роста инвестиций'
---

В Astro эти данные жестко валидируются через схему Zod в файле content.config.ts. Если вы случайно напишете datum: вместо date: или укажете строку там, где ожидается число — Astro немедленно выдаст ошибку типизации еще на этапе разработки, не позволив сломанному контенту попасть в продакшен.

Часть 2: Стандартный Markdown-текст

После frontmatter следует обычный текст. Весь синтаксис классического Markdown работает в MDX без изменений:

## Заголовок второго уровня

Обычный параграф текста с **жирным** и _курсивом_.

- Элемент списка 1
- Элемент списка 2

> Цитата или важное примечание

```javascript
const result = 1000 * Math.pow(1 + 0.1, 10);
console.log(result); // 2593.74
` ``
```

Часть 3: JSX-компоненты внутри текста

Это главная «магия» MDX. Прямо в середине текстовой статьи вы можете вставить интерактивный компонент. Например, если вы пишете статью об инвестициях — дайте читателю живой калькулятор:

Текст статьи про инвестиции и сложный процент...

Используйте наш интерактивный калькулятор:

<InvestmentCalculator client:load initialAmount={1000} years={10} rate={0.1} />

Как вы видите из результатов, при ставке 10% за 10 лет капитал...

Компонент <InvestmentCalculator> — это полноценный React или Svelte компонент с состоянием, событиями и анимациями. Он живет в отдельном файле (например, src/components/InvestmentCalculator.tsx), а в MDX вы просто его вызываете, как HTML-тег.

MDX в Astro: Продвинутые возможности

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

Глобальные компоненты: нет импортам в тексте

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

import { ArticleGrid } from '../../components/ArticleGrid.astro';

<ArticleGrid>...</ArticleGrid>

Это добавляет лишний технический «мусор» в контент и требует от редактора понимания файловой системы проекта. Astro решает эту проблему через components prop у макета (Layout):

---
// src/layouts/ArticleLayout.astro
import { MDXProvider } from '@mdx-js/react';
import ArticleGrid from '../components/ArticleGrid.astro';
import ArticleGridItem from '../components/ArticleGridItem.astro';

const components = { ArticleGrid, ArticleGridItem };
---

<slot components={components} />

После этого контент-менеджер пишет <ArticleGrid> прямо в тексте — и Astro сам знает, что это за компонент и как его отрендерить. Никаких импортов.

Переопределение стандартных тегов Markdown

Это одна из самых элегантных возможностей: вы можете «перехватить» любой стандартный HTML-тег, который генерирует Markdown, и заменить его своим компонентом.

Например, каждый блок кода в Markdown генерирует тег <pre><code>. Но вы хотите, чтобы все блоки кода отображались с вашим красивым компонентом с кнопкой «Копировать» и подсветкой синтаксиса. Достаточно прописать переопределение:

// astro.config.mjs
import mdx from '@astrojs/mdx';
import { rehypeHighlight } from 'rehype-highlight';

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

Теперь каждый тройной блок кода ``` в любой MDX-статье автоматически получит подсветку синтаксиса без единой строчки JSX в тексте.

Remark и Rehype плагины

MDX использует под капотом цепочку процессоров: Remark (работает с AST синтаксического дерева Markdown) и Rehype (работает с HTML AST перед финальным рендером).

Это мощная точка расширения. Через плагины вы можете:

• remark-gfm — включить расширенный синтаксис GitHub Flavored Markdown (таблицы, зачеркнутый текст).
• remark-smartypants — автоматически заменять прямые кавычки на «типографские», дефисы — на тире.
• rehype-slug — автоматически добавлять id к заголовкам для создания якорных ссылок.
• rehype-autolink-headings — добавлять кликабельные символы # рядом с каждым заголовком (как на GitHub).

Content Collections и MDX в Astro

Ключевой паттерн работы с MDX-контентом в Astro — Content Collections (Коллекции контента). Вместо того чтобы вручную читать файлы через import.meta.glob(), вы описываете схему коллекции в файле content.config.ts:

// content.config.ts
import { defineCollection, z } from 'astro:content';

const articles = defineCollection({
  loader: glob({ pattern: '**/*.mdx', base: './src/content/articles' }),
  schema: ({ image }) =>
    z.object({
      title: z.string().min(10).max(100),
      metaTitle: z.string().max(60),
      description: z.string().max(160),
      date: z.coerce.date(),
      author: z.string(),
      tags: z.array(z.string()),
      cover: image(),
      coverAlt: z.string(),
    }),
});

export const collections = { articles };

После этого в любом .astro-компоненте вы получаете полностью типизированный доступ к контенту:

---
import { getCollection } from 'astro:content';

// TypeScript знает все поля, подсказывает их в IDE
const articles = await getCollection('articles');
const sorted = articles.sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf());
---

Если в каком-либо .mdx-файле date окажется строкой в неправильном формате или будет превышен лимит символов description — вы узнаете об этом до деплоя, а не после жалобы пользователя.

MDX vs Markdown: Когда что использовать?

MDX и SEO: Почему это важно?

MDX-файлы с Astro — это идеальная SEO-комбинация по нескольким причинам:

1. Чистый HTML на выходе: MDX компилируется в статический HTML без JavaScript. Поисковые роботы видят готовый текст, а не «пустую» страницу React-SPA.

2. Структурированные метаданные: Frontmatter (title, description) — это единый источник правды для тегов <title>, <meta description>, OpenGraph и JSON-LD разметки.

3. Быстрая загрузка: Никакого клиентского JS-рантайма для отображения текста. Интерактивные острова загружаются отдельно и только по требованию (client:visible).

4. Легкость обновления: Редактирование статьи — это редактирование текстового файла. Никакой базы данных, никаких API, никаких локов и транзакций.

Итог

MDX — это мост между писателями и программистами. Он возвращает контроль над контентом авторам, позволяя создавать насыщенные интерактивные истории без глубокого погружения в программирование. Одновременно он сохраняет архитектуру проекта чистой и масштабируемой.

В связке с Astro Content Collections, Zod-валидацией и системой глобальных компонентов MDX превращается из простого «Markdown с компонентами» в полноценную, типобезопасную систему управления контентом, которая масштабируется от персонального блога до крупного медиа-издания.