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[]	Полный список дистрибутивов для переключателя (остальные будут заглушками без версий)
sections	SectionInfo[]	Группировка дистрибутивов в именованные разделы (см. ниже)

Разделы (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, в порядке объявления
• Дистрибутивы без секции, без -e2k суффикса → плоский список в начале
• Дистрибутивы без секции с суффиксом -e2k → авто-группа «Для Эльбрус» в конце

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

Если sections не передан в опциях явно, плагин ищет sections.json в корне проекта (process.cwd()). Конвертер publican-docbook-to-vitepress-markdown пишет этот файл при per-branch деплое — ручных изменений в .vitepress/config/index.mts не требуется.

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

Компонент 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[] }
}

interface SectionInfo {
  name: string      // заголовок группы
  distros: string[] // slugs дистрибутивов в группе
}

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

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

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

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