Changelog

Changelog в контексте MDX представляет собой систематизированный журнал изменений, отражающий эволюцию документации, компонентов и функциональности приложения. В отличие от обычного текста, MDX позволяет комбинировать Markdown и JSX, что делает Changelog интерактивным, структурированным и легко поддерживаемым.

Основная структура Changelog

В MDX Changelog часто строится вокруг версий проекта. Каждая версия сопровождается списком изменений, разделенных по категориям. Стандартная структура включает:

## [Версия 1.2.0] - 2026-03-01

### Добавлено
- Новый компонент `<TableSortable>` для интерактивных таблиц.
- Поддержка темной темы в `<CodeBlock>`.

### Изменено
- Обновлен парсер Markdown для корректного рендеринга вложенных списков.
- Оптимизирован процесс сборки статики.

### Исправлено
- Исправлена ошибка с некорректной подгрузкой изображений в Safari.
- Устранен баг с ререндером `<Chart>` при изменении пропсов.

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

## [Версия] - Дата — заголовок уровня 2, указывающий конкретный релиз.
Подзаголовки ### Добавлено, ### Изменено, ### Исправлено — категории изменений.
Каждый элемент списка — отдельное изменение, можно включать JSX для интерактивного контента.

Интерактивные элементы в Changelog

MDX позволяет вставлять JSX внутри Markdown, что дает возможность добавлять в Changelog динамические элементы:

### Добавлено
<TableSortable data={changelogData} />
<Notice type="info">
  Эта версия включает обновления безопасности.
</Notice>

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

Использование внешних данных

Часто Changelog формируется на основе внешних источников — JSON или Markdown файлов. Пример подключения данных:

import changelogData from './changelog.json';

export default function Changelog() {
  return (
    <div>
      {changelogData.map((version) => (
        <section key={version.number}>
          <h2>{version.number} - {version.date}</h2>
          {Object.entries(version.changes).map(([category, items]) => (
            <div key={category}>
              <h3>{category}</h3>
              <ul>
                {items.map((item, index) => <li key={index}>{item}</li>)}
              </ul>
            </div>
          ))}
        </section>
      ))}
    </div>
  );
}

Это позволяет:

Автоматически обновлять Changelog при добавлении новой версии.
Сохранять единый источник правды для документации.
Легко интегрировать Changelog в статические сайты, созданные с помощью Next.js или Gatsby.

Форматирование и визуальные улучшения

MDX поддерживает расширенное форматирование, что важно для Changelog:

Выделение текста: **важно** или <strong>важно</strong>
Ссылки на коммиты или pull request: [PR #42](https://github.com/...)
Блоки кода с подсветкой:

console.log('Версия 1.2.0 выпущена!');

Уведомления и предупреждения: через кастомные компоненты <Notice type="warning">...</Notice>.

Автоматизация Changelog

MDX отлично интегрируется с инструментами автоматизации:

Генерация на основе git log с помощью changelog-generator.
Форматирование изменений в MDX через скрипты на Node.js.
Интеграция с CI/CD для публикации обновлений автоматически.

Пример автоматического преобразования JSON в MDX:

import fs from 'fs';
import { jsonToMdx } from 'mdx-changelog-utils';

const changelog = JSON.parse(fs.readFileSync('changelog.json', 'utf-8'));
const mdxContent = jsonToMdx(changelog);
fs.writeFileSync('CHANGELOG.mdx', mdxContent);