Валидация сгенерированного контента

Понимание структуры MDX

MDX (Markdown + JSX) позволяет встраивать React-компоненты непосредственно в Markdown. Сгенерированный контент в MDX может содержать:

  • Обычный Markdown (заголовки, списки, ссылки, изображения)
  • JSX-компоненты
  • Импортированные функции и данные

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

Основные типы ошибок в сгенерированном MDX

  1. Синтаксические ошибки Markdown

    • Неправильно закрытые списки или блоки кода
    • Отсутствие обязательных заголовков или атрибутов в FrontMatter

  2. Ошибки JSX

    • Несуществующие компоненты
    • Неправильное использование пропсов
    • Отсутствие ключей при рендеринге списков

  3. Безопасность контента

    • Вставка произвольного JavaScript-кода
    • Попытки выполнения внешних вызовов через компонентные пропсы

Подходы к валидации

1. Статическая проверка структуры MDX

Использование библиотек типа remark и rehype для разбора Markdown и JSX позволяет анализировать AST (Abstract Syntax Tree) документа. Основные шаги:

  • Парсинг документа через remark-parse и remark-mdx

  • Прогон AST через кастомные плагины для проверки структуры:

    • Проверка наличия обязательных заголовков
    • Проверка уникальности идентификаторов для заголовков
    • Проверка правильности вложенности элементов Markdown

2. Валидация JSX-компонентов

Проверка компонентов включает:

  • Проверку, что все используемые компоненты импортированы
  • Проверку типов пропсов, например через TypeScript или PropTypes
  • Контроль запрещённых компонентов для ограничения безопасности

Пример использования TypeScript для валидации:

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

interface Props {
  content: string;
}

const components = { MyComponent };

function RenderMDX({ content }: Props) {
  return <MDXProvider components={components}>{content}</MDXProvider>;
}

В этом примере, если content содержит несуществующий компонент, TypeScript или линтер выявит ошибку.

3. Проверка данных FrontMatter

FrontMatter часто используется для хранения метаданных, например:

---
title: "Пример статьи"
date: "2026-03-23"
tags: ["MDX", "Validation"]
---

Валидация включает:

  • Проверку обязательных полей (title, date)
  • Проверку формата даты через регулярные выражения или библиотеки вроде date-fns
  • Проверку допустимых значений для тегов

Пример кода:

import matter from 'gray-matter';

const file = matter(mdxContent);

if (!file.data.title) throw new Error('Отсутствует заголовок');
if (!/^\d{4}-\d{2}-\d{2}$/.test(file.data.date)) throw new Error('Неверный формат даты');

4. Динамическая валидация при рендеринге

Некоторые проверки невозможно выполнить статически, например проверка того, что переданный пропс содержит корректный URL. Для этого можно использовать:

  • Хуки React (useEffect) для проверки значений пропсов
  • Высшие компоненты, оборачивающие MDX-компоненты и проверяющие их параметры
  • Логирование ошибок для отслеживания проблем в рантайме
function SafeImage({ src, alt }: { src: string; alt: string }) {
  if (!/^https?:\/\//.test(src)) {
    console.error('Недопустимый URL изображения:', src);
    return null;
  }
  return <img src={src} alt={alt} />;
}

5. Интеграция с линтерами и сборщиками

  • ESLint с плагином eslint-plugin-mdx помогает проверять синтаксис JSX в MDX
  • Webpack и Vite позволяют обрабатывать ошибки импорта компонентов до выполнения приложения
  • Prettier для проверки форматирования Markdown и JSX

Автоматизация процесса

  • Создание тестов для MDX-документов через Jest и React Testing Library
  • Генерация схем для FrontMatter и их проверка через zod или yup
  • Регулярное прогонка CI/CD пайплайна с проверкой всех MDX-файлов на ошибки

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

  • Валидация должна быть многоуровневой: статическая + динамическая
  • FrontMatter и JSX требуют отдельного подхода
  • Безопасность критична: любые данные, особенно от внешних источников, должны проверяться
  • Использование AST и линтеров значительно снижает вероятность ошибок до выполнения кода

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

Оглавление