@ampernic/vitepress-theme-alt-docs

Shared VitePress тема для сайтов документации ALT Linux. Включает компоненты, composables и конфигурационные хелперы — всё необходимое для запуска версионированного мультисайта документации на VitePress.

Установка

npm install @ampernic/vitepress-theme-alt-docs

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

Theme

// .vitepress/theme/index.ts
import Theme from '@ampernic/vitepress-theme-alt-docs'
export default Theme

Config helpers

// .vitepress/config/index.mts
import { defineConfigWithTheme } from 'vitepress'
import { createSharedConfig } from '@ampernic/vitepress-theme-alt-docs/config'
import { ru } from './ru'

const shared = createSharedConfig({
  distroName: 'alt-domain',
  allDistros: ['alt-domain', 'alt-workstation', 'alt-virtualization-pve', 'group-policy'],
  // Группировка дистрибутивов в подменю (необязательно):
  sections: [
    { name: 'Альт Виртуализация', distros: ['alt-virtualization-pve'] },
    { name: 'Групповые политики', distros: ['group-policy'] },
  ],
})

export default defineConfigWithTheme({
  ...shared,
  locales: { root: { label: 'Русский', ...ru } },
})

Опции createSharedConfig

| Опция | Тип | Описание | |-------|-----|----------| | distroName | string | Slug текущего дистрибутива | | allDistros | string[] | Полный список дистрибутивов для переключателя | | sections | SectionInfo[] | Именованные группы дистрибутивов в переключателе продуктов | | hostname | string | Hostname для sitemap | | editLinkRepo | string | URL репозитория для «Предложить правки» |

Компоненты

| Компонент | Описание | |-----------|----------| | ADBranding | Логотип и брендинг ALT Linux в навбаре | | ADProducts | Переключатель продуктов/дистрибутивов | | ADProductsSidebar | Боковая панель с выбором продукта | | ADVersioning | Переключатель версий документации | | ADNavBarSearch | Кнопка открытия глобального поиска в навбаре | | ADGlobalSearch | Глобальный поиск по всем дистрибутивам через Pagefind mergeIndex | | ADSearch | Компонент поиска для одного сайта (Pagefind) | | ADAssetLink | Ссылка на файл-ассет | | ADInlineImage | Встроенное изображение с нормализацией пути |

ADGlobalSearch

Поисковая модалка для индексного сайта, объединяющая индексы всех задеплоенных дистрибутивов.

Как работает:

1. Последовательно пробует import(/{distro}/pagefind/pagefind.js) для каждого дистрибутива из списка
2. HEAD-проверяет pagefind-entry.json для остальных дистрибутивов — только подтверждённые идут в mergeIndex

   Важно: вызов mergeIndex() для несуществующего пути необратимо ломает SharedWorker Pagefind, все последующие запросы тоже падают

3. Загружает pagefind/distro-meta.json с каждого сайта — получает точный список версий по дистрибутиву

   pagefind.filters() при объединённых индексах возвращает значения со всех сайтов без изоляции, поэтому для dropdown версий используется manifest, а не API Pagefind

4. Отображает фильтры по дистрибутиву и версии; при смене дистрибутива версии обновляются из manifest

Включённые плагины

Тема автоматически подключает:

• @ampernic/vitepress-plugin-pagefind — статический поиск
• @ampernic/vitepress-plugin-cross-site-router — межсайтовая навигация
• @ampernic/vitepress-plugin-html-image — нормализация <img src> в raw HTML
• @ampernic/vitepress-plugin-alt-docs-versioning — версионирование
• vitepress-plugin-tabs — вкладки в Markdown
• @nolebase/vitepress-plugin-enhanced-readabilities — улучшенная читаемость
• markdown-it-kbd — синтаксис клавиш [[Ctrl+C]]
• @alt-gnome/markdown-it-custom-containers — кастомные контейнеры

Лицензия

GPL-3.0-or-later