Открыть сервис
Главная → Блог → MDX

MDX

MDX — это формат файлов, сочетающий синтаксис Markdown (облегчённого языка разметки) для оформления текстового контента с возможностью встраивания и использования компонентов, написанных на языке JavaScript (в частности, в среде React). MDX позволяет создавать документы, в которых обычный текст, таблицы, изображения и ссылки дополняются интерактивными элементами, динамическими данными и визуализациями, управляемыми программным кодом.

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

История и происхождение

MDX был создан в 2018 году Джоном Отуотером (John Otander) и Брентом Джексоном (Brent Jackson) как часть экосистемы инструментов для работы с разметкой и компонентами. Первоначально проект развивался в рамках сообщества разработчиков, использующих JavaScript-библиотеку React. Идея заключалась в том, чтобы позволить авторам документации и блогов импортировать и использовать React-компоненты непосредственно в файлах Markdown, не прибегая к отдельным шаблонизаторам или сложным сборкам.

В 2019 году проект был передан под управление организации «MDX-js», которая занимается его дальнейшей стандартизацией и поддержкой. Ключевым этапом стал выпуск версии MDX 2.0 в 2021 году, которая принесла значительные улучшения: новый парсер, основанный на грамматике micromark, поддержку синтаксиса ESM (ECMAScript Modules) и улучшенную обработку ошибок. Версия 2.0 также абстрагировалась от прямой привязки к React, позволяя использовать MDX с другими фреймворками, такими как Vue, Svelte или Preact, через систему раннеров.

В 2023 году вышла версия MDX 3.0, которая сосредоточилась на повышении производительности парсинга и улучшении совместимости с современными стандартами JavaScript.

Синтаксис и возможности

MDX расширяет стандартный синтаксис Markdown, добавляя в него возможности, характерные для языков программирования.

Основы Markdown

В MDX поддерживается весь стандартный синтаксис Markdown: заголовки (#, ##, ###), списки (нумерованные и маркированные), таблицы, ссылки, изображения, блоки кода (с указанием языка для подсветки), цитаты и выделение текста (жирный, курсив).

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

Главная особенность MDX — возможность импортировать и использовать компоненты, написанные на JavaScript (обычно в формате JSX). Компоненты встраиваются в текст документа так же, как и обычные HTML-теги, но с поддержкой свойств (props) и дочерних элементов.

Пример встраивания React-компонента:

``` import Chart from './components/Chart.jsx'

Результаты эксперимента

Ниже представлен график, построенный на основе данных эксперимента.

<Chart data={[1, 2, 3, 4, 5]} type="line" />

Как видно из графика, наблюдается линейный рост показателя. ```

В этом примере компонент Chart принимает массив данных и тип графика в качестве свойств. Парсер MDX обрабатывает JSX-синтаксис внутри файла, преобразуя его в исполняемый код.

Использование выражений JavaScript

MDX позволяет встраивать произвольные выражения JavaScript в фигурных скобках {}. Это может быть вычисление значения, вызов функции или обращение к переменной.

Пример:

``` import { formatDate } from './utils.js'

Сегодняшняя дата: {formatDate(new Date())}

Сумма чисел: {2 + 2} ```

Импорт модулей

В MDX-файлах можно импортировать не только компоненты, но и любые другие JavaScript-модули: функции, константы, данные из JSON-файлов, стили (CSS) и т.д. Импорт осуществляется с помощью синтаксиса import (ESM), который поддерживается в современных средах выполнения.

Экспорт

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

Пример:

``` export const title = 'Глава 3. Сложные алгоритмы'

{title}

Текст главы... ```

Архитектура и процесс компиляции

MDX не является исполняемым форматом напрямую в браузере. Файлы .mdx проходят процесс компиляции (транспиляции) в обычный JavaScript-код. Этот процесс обычно выполняется на этапе сборки проекта с помощью инструментов, таких как Webpack, Vite, Rollup или Next.js.

Этапы компиляции

  1. Парсинг (Parsing): Исходный MDX-файл разбивается на синтаксические элементы: блоки Markdown (заголовки, параграфы, списки), блоки JSX (компоненты, выражения) и блоки кода. Для этого используется библиотека micromark (для Markdown) и парсер JSX.
  2. Преобразование (Transformation): Парсер создаёт абстрактное синтаксическое дерево (AST). На этом этапе происходит разрешение импортов и экспортов, а также валидация синтаксиса.
  3. Генерация кода (Code Generation): На основе AST генерируется итоговый JavaScript-модуль. Markdown-контент преобразуется в вызовы функций, создающих React-элементы (или элементы других фреймворков), а JSX-компоненты остаются в своём первоначальном виде. Полученный код может быть импортирован и использован в приложении как обычный React-компонент.

Раннеры

Для поддержки разных фреймворков MDX использует концепцию раннеров (runners). Раннер — это функция, которая определяет, как именно генерировать код для конкретной среды. Например, @mdx-js/react генерирует компоненты для React, а @mdx-js/vue — для Vue. Это позволяет использовать MDX вне зависимости от выбранного фронтенд-фреймворка.

Применение

MDX используется в различных областях веб-разработки и создания контента.

Системы документации

Наиболее распространённая область применения — документация к программному обеспечению. MDX позволяет создавать живые примеры кода, встраивать интерактивные демонстрации компонентов (например, с помощью Storybook), отображать динамические графики и таблицы с данными, а также импортировать схемы и диаграммы.

Примеры проектов, использующих MDX для документации: Gatsby, Next.js, Docusaurus, Storybook.

Блоги и сайты

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

Образовательные платформы

В образовательных целях MDX позволяет создавать учебные материалы с интерактивными заданиями, встроенными средами для выполнения кода (например, CodeSandbox или CodePen) и автоматически проверяемыми тестами.

Статические генераторы сайтов

Многие современные статические генераторы сайтов (SSG), такие как Next.js, Gatsby и Astro, имеют встроенную или легко настраиваемую поддержку MDX. Это позволяет разработчикам сочетать преимущества статической генерации контента (быстрая загрузка, SEO-оптимизация) с динамическими возможностями JavaScript.

Преимущества и недостатки

Преимущества

Недостатки

Инструменты и экосистема

Критика

Основная критика MDX связана с его сложностью для неподготовленных авторов контента. Если Markdown может освоить любой пользователь, то для работы с MDX требуется хотя бы базовое понимание JavaScript и модульной системы. Это создаёт барьер для входа для технических писателей, не знакомых с программированием.

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

Источники

  1. Официальная документация MDX: «MDX — Markdown for the component era» (mdxjs.com).
  2. Документация Next.js: «Using MDX with Next.js» (nextjs.org).
  3. Документация Gatsby: «MDX and Gatsby» (gatsbyjs.com).
  4. Статья «Introducing MDX 2.0» в блоге команды MDX (mdxjs.com/blog).
  5. Статья «MDX 3.0: What’s new» в блоге команды MDX (mdxjs.com/blog).
  6. Репозиторий проекта MDX на GitHub (github.com/mdx-js/mdx).

BFOmetr — база данных и аналитика по компаниям России.

На главную BFOmetr →

Похожие материалы