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-breadcrumbs	Хлебные крошки над контентом
vitepress-plugin-cross-site-router	Межсайтовая навигация
vitepress-plugin-single-page	Одностраничное представление версии
vitepress-plugin-export	Экспорт версии в PDF / HTML / EPUB
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	Переключатель дистрибутивов
doc-before	Хлебные крошки
aside-outline-before	Кнопка экспорта / переключатель форматов
home-hero-before	Главная (карточки продуктов) на layout: home

Главная и лендинги

Главная (layout: home)

Главная страница (индекс-сайт) использует layout: home; контент рисуют компоненты темы по данным из frontmatter altHome:

---
layout: home
altHome:
  hero:
    logo: basealt
    title: Документация «Базальт СПО»
    text: Официальная документация ОС «Альт».
  products:
    alt-server:
      tagline: Комплексное серверное решение для ИТ-инфраструктуры
      accent: '#8e96a3'
      grad: ['#c8d0dd', '#8e96a3']
  footer:
    links:
      - { title: Сайт компании, url: https://www.basealt.ru/ }
    copyright: © 2026 «Базальт СПО»
---

Список дистрибутивов и разделы берутся из __VERSIONS_DATA__ (плагин версионирования); altHome.products[<slug>] задаёт теглайн и акцентный цвет карточки (имя по умолчанию — из общего справочника).

Лендинг дистрибутива

Шаблон лендинга выводит <VersionList distro="<slug>" /> — релизы, сгруппированные по мажорным версиям, карточками со списками и бейджем «Актуальная».

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

Тема ожидает файлы в 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. Поиск фильтруется по текущей версии страницы.