vitepress-theme-alt-docs

Общая тема VitePress для документации ALT Linux. Объединяет все пакеты монорепозитория в готовую конфигурацию.

Установка

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

Тема подтягивает остальные пакеты как зависимости автоматически.

Подключение

Тема (theme/index.ts)

export { Theme as default } from '@ampernic/vitepress-theme-alt-docs'

Конфиг (.vitepress/config/index.mts)

import { createSharedConfig } from '@ampernic/vitepress-theme-alt-docs/config'

const shared = createSharedConfig({
  distroName: 'alt-server',
  allDistros: ['alt-server', 'alt-workstation', 'alt-education'],
  hostname: 'https://docs.altlinux.org',
})

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

createSharedConfig(options)

Опция	Тип	Описание
distroName	string	Slug дистрибутива (e.g. 'alt-server')
allDistros	string[]	Список всех дистрибутивов для переключателя
hostname	string	Hostname для sitemap
editLinkRepo	string	URL Forgejo-репозитория для кнопки «Предложить правку»

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

Плагин	Что даёт
vitepress-plugin-pagefind	Поиск Pagefind с фильтрацией по версии
vitepress-alt-docs-versioning	Переключатель версий и редакций
vitepress-plugin-cross-site-router	Межсайтовая навигация
vitepress-plugin-html-image	Нормализация <img> в raw HTML
@nolebase/vitepress-plugin-enhanced-readabilities	Переключатель ширины контента
vitepress-plugin-tabs	Вкладки в Markdown
markdown-it-kbd	<kbd> синтаксис
@alt-gnome/markdown-it-custom-containers	Контейнеры left, center, right

Layout slots

Тема занимает следующие слоты VitePress:

Слот	Компонент
nav-bar-content-before	Поисковая строка (кнопка + модал)
nav-bar-content-after	Меню Nolebase (настройки читаемости)
nav-screen-content-after	Мобильное меню Nolebase
sidebar-nav-before	Переключатель дистрибутивов

Структура контента

Тема ожидает файлы в docs/ru/{version}/... с rewrite-правилом ru/:slug* → :slug*.

docs/
  ru/
    11.0/
      index.md
    11.1/
      index.md
  public/
    favicon.ico
    branding/

Поиск

Поиск работает только в production-сборке. Для индексации pagefind должен быть установлен как devDependency в проекте документации:

npm install -D pagefind

После vitepress build автоматически запускается pagefind --site .vitepress/dist. Поиск фильтруется по текущей версии страницы.