@ampernic/vitepress-plugin-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() читает эти данные

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

Vite-плагин

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

export default defineConfig({
  vite: {
    plugins: [
      VersioningPlugin({
        distroName: 'alt-server',
        allDistros: ['alt-server', 'alt-workstation', 'alt-education'],
      }),
    ],
  },
})

| Опция | Тип | Описание | |-------|-----|----------| | distroName | string | Slug текущего дистрибутива. Плагин сканирует только его версии | | allDistros | string[] | Полный список дистрибутивов для переключателя (остальные будут заглушками без версий) | | sections | SectionInfo[] | Группировка дистрибутивов в именованные разделы (см. ниже) |

Разделы (sections)

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

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)

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

Если sections не передан в опциях явно, плагин ищет sections.json в корне проекта (process.cwd()). Конвертер пишет этот файл автоматически при 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
      ...

Лицензия

GPL-3.0-or-later