Программная генерация MDX

MDX (Markdown + JSX) объединяет возможности Markdown и JSX, позволяя создавать динамический и интерактивный контент в приложениях на React. Программная генерация MDX предполагает автоматическое создание MDX-файлов или строк на основе данных, что особенно полезно для документации, блогов, технических заметок и систем управления контентом.

Структура MDX

MDX-файл может содержать три основных блока:

  1. Frontmatter – метаданные документа в формате YAML, заключённые между ---:
---
title: "Пример MDX"
date: "2026-03-23"
tags: ["javascript", "mdx"]
---
  1. Markdown-контент – текст с разметкой Markdown:
## Подзаголовок

Текст с **жирным** и *курсивным* форматированием.
  1. JSX-компоненты – возможность вставлять React-компоненты прямо в Markdown:
<MyComponent prop="value" />

Для программной генерации важно корректно формировать все три блока, особенно JSX, чтобы итоговый MDX был синтаксически правильным.

Генерация MDX на основе данных

Использование шаблонных строк

Для небольших MDX-документов удобно использовать шаблонные строки в Jav * aScript:

const generateMDX = (title, date, content, components) => `
---
title: "${title}"
date: "${date}"
---

${content}

${components.map(c => `<${c.name} ${Object.entries(c.props).map(([k, v]) => `${k}="${v}"`).join(' ')} />`).join('\n')}
`;

Пояснения:

  • content – Markdown-текст, который может включать заголовки, списки и другие элементы.
  • components – массив объектов с name и props, для генерации JSX-компонентов.
  • Object.entries(c.props) преобразует свойства объекта в атрибуты JSX.

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

const mdxContent = generateMDX(
  "Автоматическая генерация",
  "2026-03-23",
  "Пример текста с **жирным** шрифтом.",
  [{ name: "Alert", props: { type: "warning", message: "Внимание!" } }]
);

Динамическая вставка данных

MDX позволяет программно вставлять переменные через JSX. Для генерации динамического контента часто создают компонент-обёртку:

import { useState } from 'react';

const DataWrapper = ({ data }) => (
  <ul>
    {data.map((item, index) => <li key={index}>{item}</li>)}
  </ul>
);

При генерации MDX строку можно формировать так:

const data = ["Элемент 1", "Элемент 2"];
const mdxString = `
<DataWrapper data={${JSON.stringify(data)}} />
`;

Использование JSON.stringify гарантирует корректную сериализацию массивов и объектов в JSX.

Автоматическая генерация frontmatter

Frontmatter часто создаётся на основе внешних источников, например, базы данных или API. Пример:

const generateFrontmatter = (meta) => `
---
title: "${meta.title}"
date: "${meta.date}"
tags: [${meta.tags.map(tag => `"${tag}"`).join(', ')}]
---
`;

Интеграция с основным MDX:

const meta = { title: "MDX Автоматизация", date: "2026-03-23", tags: ["mdx", "javascript"] };
const content = "Контент документа с **Markdown** и JSX.";
const mdxDocument = generateFrontmatter(meta) + "\n" + content;

Работа с компонентами и импортами

Для корректной работы MDX необходимо включать импорты компонентов, которые будут использоваться внутри документа:

const generateImports = (components) => components.map(c => `import ${c} from './components/${c}.jsx';`).join('\n');

Полный пример генерации MDX с импортами:

const components = ["Alert", "Chart"];
const imports = generateImports(components);

const mdxDocument = `
${imports}

# Заголовок документа

<Alert type="info" message="Это автоматически сгенерированное сообщение" />
<Chart data={[1,2,3,4]} />
`;

Сложные сценарии: циклы и условные вставки

Программная генерация MDX может включать циклы для создания повторяющихся блоков:

const items = ["Пункт A", "Пункт B", "Пункт C"];
const listMDX = items.map(item => `- ${item}`).join('\n');

Условные вставки позволяют включать контент только при определённых условиях:

const showAlert = true;
const alertMDX = showAlert ? `<Alert type="success" message="Успех!" />` : '';

Итоговый MDX-документ объединяет все части:

const mdxDocument = `
# Список элементов

${listMDX}

${alertMDX}
`;

Генерация больших MDX-документов

При больших объёмах текста и динамических компонентов рекомендуется:

  1. Разбивать контент на модули, чтобы легче было управлять вставками.
  2. Использовать функции для генерации повторяющихся блоков (таблицы, списки, карточки).
  3. Применять сериализацию данных через JSON.stringify для корректного встраивания массивов и объектов.
  4. Включать все необходимые импорты компонентов в начале MDX.
  5. Проверять итоговый документ с помощью @mdx-js/mdx для валидации синтаксиса.

Эти практики обеспечивают стабильную генерацию MDX независимо от масштаба документа и сложности контента.

Оглавление