vitepress-alt-docs-versioning

Плагин версионирования документации для VitePress. Сканирует файловую структуру при сборке, инжектирует данные о версиях/редакциях через define, предоставляет компонент и composable для отображения версии.

Установка

npm install @ampernic/vitepress-plugin-alt-docs-versioning

Концепция

Документация организована по схеме docs/ru/{version}/.... Плагин:

1. Сканирует директорию docs/ru/ и находит все версии (директории вида 11.0, 11.1, 11.1-edu и т.д.)
2. Компилирует данные в объект VersionInfo и инжектирует его через Vite define как __VERSIONS_DATA__
3. Клиентский composable useVersionsData() читает эти данные

Поддерживается режим single distro (один сайт = один дистрибутив) и multi distro (один сайт = несколько дистрибутивов).

Использование

Vite-плагин

import { VersioningPlugin } from '@ampernic/vitepress-plugin-alt-docs-versioning'

export default defineConfig({
  vite: {
    plugins: [
      VersioningPlugin({
        distroName: 'alt-server',   // slug текущего дистрибутива
        allDistros: ['alt-server', 'alt-workstation', 'alt-education'],
      }),
    ],
  },
})

Опция	Тип	Описание
distroName	string	Slug текущего дистрибутива. Плагин сканирует только его версии
allDistros	string[]	Полный список дистрибутивов для переключателя (остальные будут заглушками без версий). Если рядом с конфигом лежит distros.json, он важнее опции
sections	SectionInfo[]	Группировка дистрибутивов в именованные разделы (см. ниже). Если рядом лежит sections.json, он используется при пустом sections
debug	boolean	Однострочный отчёт при сборке: режим (per-distro, multi-scan, ...), число дистрибутивов, версии текущего дистрибутива, число секций. При использовании темы включается через createSharedConfig({ debug: true })

Разделы (sections)

Позволяют объединить несколько дистрибутивов под общим подменю в переключателе продуктов (ADProducts):

VersioningPlugin({
  distroName: 'alt-domain',
  allDistros: ['alt-domain', 'alt-workstation', 'alt-virtualization-pve', 'alt-virtualisation-one', 'group-policy'],
  sections: [
    { name: 'Альт Виртуализация', distros: ['alt-virtualization-pve', 'alt-virtualisation-one'] },
    { name: 'Групповые политики', distros: ['group-policy'] },
  ],
})

Возможны два варианта секции:

• Группа: { name, distros: [<slug>, ...] } - подменю с несколькими дистрибутивами
• Плоский пункт: { name, distro: <slug> } - один пункт с отдельной подписью, без вложенного подменю

Правила формирования меню:

• Дистрибутивы из секций рендерятся в порядке объявления
• Дистрибутивы без секции, без -e2k суффикса - плоский список в начале
• Дистрибутивы без секции с суффиксом -e2k - авто-группа «Для Эльбрус» в конце

Автоматическое чтение sections.json и distros.json:

Если sections не передан явно, плагин ищет sections.json в корне проекта (process.cwd()). Аналогично allDistros подтягивается из distros.json в том же каталоге, если файл есть. Оба файла пишутся снаружи (per-branch деплой), поэтому ручных правок конфига не требуется.

[
  { "name": "Альт Виртуализация", "distros": ["alt-virtualization-pve", "alt-virtualisation-one"] },
  { "name": "Групповые политики", "distros": ["group-policy"] }
]

distros.json - просто массив slug'ов:

["alt-server", "alt-workstation", "alt-education"]

Компонент ADVersioning

Готовый компонент переключателя версий:

<script setup>
import { ADVersioning } from '@ampernic/vitepress-plugin-alt-docs-versioning/client'
</script>

<template>
  <ADVersioning />
</template>

Используйте через app.component() в enhanceApp или непосредственно в .vitepress/theme.

Composable useVersionsData()

import { useVersionsData } from '@ampernic/vitepress-plugin-alt-docs-versioning/client'

const data = useVersionsData()
// data.distros['alt-server'].versions -> ['11.0', '11.1']
// data.distros['alt-server'].latest   -> '11.1'

Типы

interface DistroEdition {
  name: string   // отображаемое имя редакции
  path: string   // путь относительно версии
}

interface DistroInfo {
  versions: string[]
  latest: string
  title?: string
  editions?: { [version: string]: DistroEdition[] }
}

// Группа (`distros`) или плоский пункт (`distro`) - взаимоисключаются.
type SectionInfo =
  | { name: string; distros: string[]; distro?: never }
  | { name: string; distro: string; distros?: never }

interface VersionsData {
  distros: { [distroName: string]: DistroInfo }
  sections?: SectionInfo[]
}

Структура файлов

Плагин ожидает следующую структуру:

docs/
  ru/
    11.0/
      index.md
      ...
    11.1/
      index.md
      ...
    11.1-edu/          # редакция через суффикс
      index.md
      ...