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

MDX-js

MDX-js (часто сокращённо MDX) — это формат файлов и инструмент для разработки веб-интерфейсов, который позволяет использовать синтаксис JSX (JavaScript XML) внутри документов, написанных на языке разметки Markdown. MDX объединяет возможности простого форматирования текста, присущие Markdown, с возможностью встраивать интерактивные компоненты, написанные на фреймворках вроде React, Vue или Svelte. Файлы MDX имеют расширение .mdx и обрабатываются компилятором, который преобразует их в JavaScript-модули, готовые к рендерингу в браузере или на сервере.

История

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

В 2021 году была выпущена версия MDX 2.0, которая стала значительным обновлением. В ней была переработана архитектура парсера, улучшена поддержка синтаксиса, добавлена возможность экспорта данных из файлов MDX и введена поддержка пользовательских типов узлов абстрактного синтаксического дерева (AST). MDX 2.0 стал более независимым от конкретного фреймворка, что позволило использовать его не только с React, но и с другими библиотеками.

В 2023 году вышла версия MDX 3.0, которая интегрировалась с новым форматом ESModule, улучшила обработку ошибок и добавила поддержку импорта компонентов из сторонних пакетов без необходимости их предварительной регистрации. Проект развивается как открытое программное обеспечение (Open Source) и поддерживается сообществом разработчиков.

Принцип работы

Компиляция

Процесс обработки файла .mdx состоит из нескольких этапов:

  1. Парсинг Markdown: Исходный текст разбивается на абстрактное синтаксическое дерево (AST) с использованием парсера, совместимого со спецификацией CommonMark. На этом этапе определяется структура документа: заголовки, абзацы, списки, ссылки, изображения и т.д.
  2. Обработка JSX: Парсер распознаёт встроенные конструкции JSX (например, <Button>Нажми меня</Button>) и выделяет их в отдельные узлы AST. При этом синтаксис Markdown и JSX может смешиваться в одном файле.
  3. Преобразование в JavaScript: Полученное AST транслируется в JavaScript-код. В результате получается функция, которая возвращает виртуальное DOM-дерево (Virtual DOM) или строку HTML. Этот код может быть импортирован как обычный модуль в приложении на React, Next.js, Gatsby или другом фреймворке.

Синтаксис

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

  • Импорт компонентов: В начале файла можно импортировать JavaScript-модули, включая React-компоненты, используя синтаксис import:

``javascript import Button from '../components/Button.jsx' ``

  • Использование JSX: Импортированные компоненты могут быть вставлены непосредственно в текст Markdown:

```mdx Нажмите на кнопку ниже, чтобы отправить форму:

<Button variant="primary" onClick={handleClick}>Отправить</Button> ```

  • Экспорт данных: Файл MDX может экспортировать переменные, функции или объекты, которые могут быть использованы в других модулях:

``javascript export const title = 'Заголовок статьи' export const metadata = { author: 'Иван', date: '2024-01-01' } ``

  • Выражения JavaScript: Внутри JSX-блоков можно использовать фигурные скобки для вставки JavaScript-выражений:

``mdx <div>Сегодня: {new Date().toLocaleDateString('ru-RU')}</div> ``

Применение

Документация

MDX широко используется для написания технической документации и руководств пользователя. Платформы вроде Docusaurus, Storybook и VitePress поддерживают MDX «из коробки». Разработчики могут встраивать в документацию интерактивные примеры кода, демонстрации компонентов, формы обратной связи и динамические графики, не покидая среды Markdown.

Блоги и сайты

Генераторы статических сайтов, такие как Next.js, Gatsby и Astro, позволяют создавать блоги, где каждая статья является файлом .mdx. Это даёт возможность авторам писать контент в простом Markdown, а разработчикам — добавлять на страницы кастомные интерактивные элементы: слайдеры, карты, калькуляторы, встроенные видео-плееры.

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

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

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

Пакеты

  • @mdx-js/mdx — основной компилятор, который преобразует MDX в JavaScript.
  • @mdx-js/react — интеграция с библиотекой React, предоставляющая компонент MDXProvider для настройки рендеринга элементов Markdown.
  • @mdx-js/loader — загрузчик для Webpack, позволяющий импортировать MDX-файлы напрямую в JavaScript-код.
  • @mdx-js/node-loader — загрузчик для Node.js, позволяющий запускать MDX-файлы на сервере.

Интеграция с фреймворками

  • Next.js: Поддерживает MDX через плагин @next/mdx. Статьи могут быть размещены в папке pages или импортированы в компоненты.
  • Gatsby: Имеет плагин gatsby-plugin-mdx, который обрабатывает MDX-файлы и создаёт из них страницы.
  • Astro: Нативно поддерживает MDX, позволяя использовать компоненты из любых фреймворков (React, Vue, Svelte) внутри Markdown-контента.
  • VitePress: Использует MDX для создания документации, поддерживая встраивание Vue-компонентов.

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

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

  • Гибкость: Позволяет сочетать простой текст с мощными интерактивными элементами.
  • Удобство для авторов: Авторы контента могут писать в привычном Markdown, не изучая JavaScript.
  • Модульность: Компоненты могут быть переиспользованы в разных файлах MDX.
  • Совместимость: Работает с большинством современных фреймворков и сборщиков.

Недостатки

  • Сложность отладки: Ошибки в JSX-коде внутри MDX могут быть трудны для диагностики, так как компилятор генерирует промежуточный код.
  • Зависимость от сборки: Для использования MDX требуется этап сборки (компиляции), что может замедлить разработку простых статических сайтов.
  • Ограничения безопасности: Встраивание произвольного JavaScript-кода через MDX может представлять угрозу XSS (межсайтовый скриптинг), если не настроена санитизация ввода.

Сравнение с альтернативами

  • Markdown: Обычный Markdown не поддерживает встраивание интерактивных компонентов. Для добавления динамики требуется отдельный JavaScript-файл.
  • JSX: Чистый JSX не имеет синтаксиса Markdown для форматирования текста (заголовки, списки), что делает его менее удобным для написания длинных текстов.
  • HTML: HTML-шаблоны громоздки для написания контента, и в них сложнее поддерживать читаемость исходного кода.
  • MDX занимает промежуточное положение, предоставляя лучшие черты обоих миров.

Интересные факты

  • MDX не является языком разметки в строгом смысле, а скорее форматом данных, который компилируется в JavaScript.
  • Проект MDX изначально назывался «MDX» как сокращение от «Markdown + JSX».
  • В MDX 2.0 была введена возможность экспорта данных, что позволило использовать MDX-файлы как источник метаданных (например, для конфигурации сайта).
  • Некоторые платформы, такие как CodeSandbox и StackBlitz, используют MDX для создания интерактивных примеров кода в документации.

Источники

  • Официальная документация MDX (mdxjs.com)
  • Репозиторий проекта на GitHub (mdx-js/mdx)
  • Статья «Introducing MDX» в блоге компании Gatsby (2018)
  • Документация Next.js по работе с MDX
  • Документация VitePress по работе с MDX

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

На главную BFOmetr →

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