Compile API

Compile API в библиотеке MDX представляет собой низкоуровневый инструмент для компиляции MDX-документов в JavaScript-код. Он позволяет конвертировать сочетание Markdown и JSX в исполняемый модуль, который может быть импортирован и использован в React-приложении. Это особенно полезно для динамической генерации контента и интеграции MDX в собственные сборочные процессы.

Основные функции и структура

MDX предоставляет функцию compile из пакета @mdx-js/mdx, которая принимает строку с содержимым MDX и возвращает результат компиляции. Результат содержит:

  • value — сгенерированный JavaScript-код, который можно интерпретировать как модуль.
  • data — метаданные, включающие экспортированные значения, настройки и информацию о фронтматтере.

Пример базового вызова:

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

const mdxSource = `
# Заголовок

Это текст с **Markdown** разметкой.

<MyComponent />
`;

const result = await compile(mdxSource, {
  outputFormat: 'program',
  providerImportSource: '@mdx-js/react'
});

console.log(result.value);

Опции Compile API

outputFormat

Определяет формат выходного кода:

  • 'program' — стандартный JavaScript модуль.
  • 'function-body' — только тело функции без обертки модуля.
  • 'function' — полностью сгенерированная функция для рендера.

jsx

Позволяет задать JSX-функцию для генерации компонентов:

const result = await compile(mdxSource, { jsx: true });

Если используется jsx: false, компиляция вернет только AST Markdown без JSX.

remarkPlugins и rehypePlugins

Позволяют подключать плагины для обработки Markdown и HTML соответственно:

import remarkGfm from 'remark-gfm';
import rehypeHighlight from 'rehype-highlight';

const result = await compile(mdxSource, {
  remarkPlugins: [remarkGfm],
  rehypePlugins: [rehypeHighlight]
});
  • remarkPlugins — работают на уровне синтаксического дерева Markdown (например, поддержка таблиц, списков задач, ссылок).
  • rehypePlugins — работают на уровне HTML, позволяя добавлять классы, подсветку синтаксиса, оптимизацию тегов.

providerImportSource

Позволяет указать источник для компонента MDXProvider:

const result = await compile(mdxSource, {
  providerImportSource: '@mdx-js/react'
});

Это важно для интеграции с React, когда нужно использовать собственные компоненты для рендера MDX-контента.

Работа с фронтматтером

MDX поддерживает YAML-фронтматтер для хранения метаданных документа. Compile API автоматически парсит фронтматтер и помещает его в объект data.

const mdxSource = `
---
title: "Пример статьи"
date: "2026-03-23"
---

# Заголовок
`;

const result = await compile(mdxSource, { parseFrontmatter: true });
console.log(result.data.frontmatter);
// { title: "Пример статьи", date: "2026-03-23" }

Опция parseFrontmatter активирует автоматическую обработку фронтматтера.

Генерация AST и промежуточных форматов

Compile API позволяет получать промежуточные формы документа:

  • MDXAST — дерево Markdown+JSX
  • HAST — HTML-представление AST
  • JavaScript — финальный скомпилированный модуль

Пример извлечения AST:

import { compile } from '@mdx-js/mdx';
import { toString } from 'hast-util-to-string';

const result = await compile(mdxSource, { outputFormat: 'program' });
console.log(result.value); // сгенерированный код

Это удобно для анализа содержимого MDX перед рендером или для интеграции в собственные системы преобразования.

Асинхронная и синхронная компиляция

Compile API поддерживает как асинхронный, так и синхронный режим:

  • Асинхронный (await compile(...)) — предпочтителен при использовании плагинов, которые выполняют асинхронные операции (например, загрузка внешних данных).
  • Синхронный (compileSync(...)) — работает для простых документов без асинхронных плагинов.
import { compileSync } from '@mdx-js/mdx';

const result = compileSync(mdxSource, { outputFormat: 'program' });
console.log(result.value);

Синхронная версия быстрее и подходит для статической компиляции в сборках.

Примеры интеграции с React

Скомпилированный код можно импортировать динамически и рендерить через React:

import React from 'react';
import { MDXProvider } from '@mdx-js/react';

const components = {
  MyComponent: () => <div style={{ color: 'red' }}>Компонент</div>
};

async function renderMDX(mdxSource) {
  const { default: Content } = await eval(`(async () => { ${await compile(mdxSource, { outputFormat: 'function-body' })} })()`);
  return <MDXProvider components={components}><Content /></MDXProvider>;
}

Такой подход позволяет создавать CMS-подобные решения, где контент хранится в MDX и рендерится динамически.

Особенности и рекомендации

  • Использовать compile с remarkPlugins и rehypePlugins для расширяемости.
  • Всегда указывать providerImportSource, если нужен рендер кастомных компонентов в React.
  • Для производительных сборок лучше использовать синхронную версию compileSync при отсутствии асинхронных операций.
  • При необходимости работать с метаданными документа — включать parseFrontmatter.

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

Оглавление