Версионирование документации

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

Структура проекта для версионированной документации

Для реализации версионирования необходимо продумать организацию файлов и директорий. Обычно структура выглядит следующим образом:

docs/
├── v1.0/
│   ├── introduction.mdx
│   ├── setup.mdx
│   └── components/
├── v2.0/
│   ├── introduction.mdx
│   ├── setup.mdx
│   └── components/
├── current/
│   ├── introduction.mdx
│   ├── setup.mdx
│   └── components/
  • v1.0, v2.0 — отдельные версии документации.
  • current — текущая версия, которую чаще всего используют пользователи.
  • Внутри каждой версии можно использовать вложенные папки для модульной структуры документации, например components, api или guides.

Интеграция версий с MDX

MDX файлы импортируются и обрабатываются через систему сборки (Webpack, Vite, Next.js). Для поддержки версий можно создать конфигурацию, которая динамически выбирает путь к документации:

import fs from 'fs';
import path from 'path';

export function getDocs(version, page) {
  const docPath = path.join(process.cwd(), 'docs', version, `${page}.mdx`);
  if (!fs.existsSync(docPath)) {
    throw new Error(`Документация для версии ${version} и страницы ${page} не найдена`);
  }
  return fs.readFileSync(docPath, 'utf-8');
}

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

Управление маршрутами для разных версий

Для веб-приложений, построенных на React и Next.js, маршрутизация версий документации обычно строится на параметрах URL:

/docs/v1.0/introduction
/docs/v2.0/setup

Пример динамического маршрута в Next.js:

import { useRouter } from 'next/router';
import { getDocs } from '../. ./lib/docs';

export default function DocPage({ content }) {
  const router = useRouter();
  const { version, slug } = router.query;

  return (
    

      
    

  );
}

export async function getStaticProps({ params }) {
  const content = getDocs(params.version, params.slug);
  return { props: { content } };
}

export async function getStaticPaths() {
  // Генерация путей для всех версий и страниц
}

Обновление и поддержка нескольких версий

  • Создание новой версии: копирование текущей папки документации в новую директорию с версией, например v2.1.
  • Синхронизация изменений: для изменений, которые касаются всех версий, используется практика cherry-pick или ручное слияние.
  • Архивирование старых версий: устаревшие версии можно оставить только для чтения, избегая случайного изменения содержимого.

Плюсы использования MDX в версионированной документации

  1. Интерактивность: компоненты React можно вставлять прямо в Markdown, обеспечивая демонстрации кода, примеры UI и live-превью.
  2. Повторное использование компонентов: общие компоненты (таблицы, карточки, предупреждения) можно импортировать в разные версии документации без дублирования.
  3. Гибкая маршрутизация: через динамические маршруты можно отображать нужную версию документации по URL.
  4. Легкость миграции: новая версия создается простой копией старой, изменения легко вносятся выборочно.

Лучшие практики

  • Для каждой версии документации хранить отдельный sidebar.json или конфигурацию меню, чтобы навигация была независимой.
  • Поддерживать единый стиль компонентов через общую библиотеку React.
  • Автоматизировать сборку и деплой документации через CI/CD, чтобы новые версии публиковались без ручных шагов.
  • Помечать устаревшие страницы визуальными индикаторами (например, баннер “Deprecated”), чтобы пользователи видели, что информация не актуальна.

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

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

npx docusaurus docs:version 2.0

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

Оглавление