CLI инструменты

Для работы с MDX в JavaScript часто используется CLI-инструмент, предоставляемый официальным пакетом @mdx-js/mdx. Установка производится через npm или yarn:

npm install @mdx-js/mdx --save-dev
# или
yarn add @mdx-js/mdx --dev

После установки CLI становится доступным глобально через команду npx mdx или локально через скрипты npm. Основная задача CLI — трансформация файлов .mdx в JSX или в готовый React-компонент.

npx mdx src/content.mdx --output src/components/Content.js

Ключевые моменты:

  • src/content.mdx — исходный MDX-файл.
  • --output — путь для сгенерированного файла.

CLI поддерживает работу как с одиночными файлами, так и с целыми директориями, что особенно удобно при генерации контента для статических сайтов.

npx mdx src/posts --out-dir src/components/posts

Трансформация MDX в JSX

CLI позволяет трансформировать MDX напрямую в JSX-код, готовый для интеграции в React-проекты. Основные опции:

  • --jsx — генерирует JSX вместо стандартного JS.
  • --provider-import-source — указывает источник провайдера для контекста MDX.
  • --remark-plugins и --rehype-plugins — подключение плагинов для обработки Markdown и HTML соответственно.

Пример с подключением плагинов:

npx mdx src/content.mdx --output src/components/Content.js \
  --remark-plugins remark-slug remark-autolink-headings \
  --rehype-plugins rehype-highlight

Это позволяет автоматически добавлять идентификаторы к заголовкам, создавать ссылки на них и подсвечивать синтаксис кода.

Работа с watch-режимом

Для проектов с активной разработкой удобно использовать режим слежения (watch). MDX CLI поддерживает автоматическую пересборку файлов при их изменении:

npx mdx src/content.mdx --output src/components/Content.js --watch

Особенности watch-режима:

  • Пересборка происходит только при изменении исходных .mdx файлов.
  • Можно подключать несколько директорий для слежения одновременно.
  • Поддерживает генерацию исходного кода в указанную директорию без перезаписи остальных файлов.

Использование CLI с Node.js API

Помимо командной строки, MDX предоставляет Node.js API для интеграции трансформации напрямую в код:

import { compile } from '@mdx-js/mdx';
import fs from 'fs';

const source = fs.readFileSync('src/content.mdx', 'utf-8');

const compiled = await compile(source, {
  remarkPlugins: [require('remark-slug')],
  rehypePlugins: [require('rehype-highlight')],
});

fs.writeFileSync('src/components/Content.js', String(compiled));

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

Интеграция с пакетными менеджерами и скриптами npm

MDX CLI удобно подключать через npm-скрипты, что упрощает повторяемость операций. Например:

{
  "scripts": {
    "build:mdx": "mdx src/posts --out-dir src/components/posts",
    "watch:mdx": "mdx src/posts --out-dir src/components/posts --watch"
  }
}

Такой подход позволяет запускать компиляцию MDX из любой среды, включая CI/CD пайплайны.

Настройка плагинов CLI

MDX CLI поддерживает подключение внешних плагинов для расширения возможностей Markdown и HTML-парсинга.

Remark-плагины:

  • remark-slug — генерирует идентификаторы для заголовков.
  • remark-autolink-headings — автоматически добавляет ссылки к заголовкам.
  • remark-frontmatter — позволяет обрабатывать YAML/JSON frontmatter в MDX.

Rehype-плагины:

  • rehype-highlight — подсветка синтаксиса.
  • rehype-katex — рендеринг математических формул.
  • rehype-sanitize — очистка HTML от нежелательных тегов.

Подключение осуществляется через опции CLI или через конфигурационные файлы .mdxrc.js:

export default {
  remarkPlugins: [require('remark-slug')],
  rehypePlugins: [require('rehype-highlight')],
};

Генерация статических сайтов с MDX CLI

MDX CLI активно используется для подготовки контента в статических сайтах на Next.js, Gatsby и других фреймворках. Структура процесса:

  1. Создание MDX-файлов в отдельной директории (src/posts, src/pages).
  2. Компиляция MDX через CLI в JSX или React-компоненты.
  3. Импорт сгенерированных компонентов в страницы сайта.
  4. Использование плагинов для расширения возможностей Markdown.

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

Оглавление