vitepress-theme-alt-docs

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

Установка

bash

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 дистрибутива (например `'alt-server'`). Обязательно
`productName`	`string`	-	Отображаемое имя продукта. Проброшено в PWA manifest, `<title>`, LLM-выдачу
`allDistros`	`string[]`	-	Список всех дистрибутивов для переключателя. `distros.json` рядом с конфигом важнее
`sections`	`SectionInfo[]`	-	Группировки дистрибутивов в переключателе; `sections.json` рядом с конфигом важнее
`productLinks`	`Record<string, string>`	-	Slug -> внешняя страница продукта. Ссылка текущего дистрибутива автоматически подставляется в `export.logoLink`
`hostname`	`string`	-	Абсолютный hostname для sitemap, canonical, og:image
`editLinkRepo`	`string`	`alt-docs/docs-vitepress`	Репозиторий Forgejo для кнопки «Предложить правку»
`export`	`ExportPluginOptions`	-	Опции экспорта в PDF / HTML / EPUB. Если не задано - экспорт не запускается
`meta`	`MetaPluginOptions \| false`	значения по умолчанию	SEO / OG / canonical. `false` полностью отключает `MetaPlugin`
`llms`	`LlmsPluginOptions \| false`	значения по умолчанию	`llms.txt` / `llms-full.txt` / per-page mirror. `false` отключает
`singlePage`	`Omit<SinglePagePluginOptions, 'distroName'>`	-	Опции single-page (например `dropInitialTOC: true`)
`reportIssue`	`false \| { repo?; origin?; labels?; shortcut? }`	`alt-docs/docs-vitepress`	Ctrl+Enter -> Forgejo new-issue. `false` отключает
`optimizeImages`	`boolean \| OptimizeImagesOptions`	включено	Пережимает PNG в собранном сайте без потерь, до того как экспорт вставит их в бандлы. `false` отключает
`debug`	`boolean`	`false`	Один флаг, включающий `debug` во всех вложенных плагинах (свой `debug` в конкретной опции важнее)

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

Плагин	Что даёт
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
vitepress-plugin-meta	Canonical, sitemap, Open Graph, OG-image
vitepress-plugin-llms	`llms.txt`, `llms-full.txt`, per-page markdown-зеркало
vitepress-plugin-report-issue	Ctrl+Enter -> заготовка issue в Forgejo
alt-docs-registry	Общий реестр дистрибутивов (`products.yaml`)
`@nolebase/vitepress-plugin-enhanced-readabilities`	Переключатель ширины контента
`vitepress-plugin-tabs`	Вкладки в Markdown
`markdown-it-kbd`	`<kbd>` синтаксис
`markdown-it-attrs`	`{#id .class}` после заголовков
`@alt-gnome/markdown-it-custom-containers`	Контейнеры `left`, `center`, `right`

Layout slots

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

Слот	Компонент
`layout-top`	`ReportIssueDialog` (модалка «Сообщить о проблеме»)
`nav-bar-content-before`	Поисковая строка (кнопка + модал)
`nav-bar-content-after`	Меню Nolebase (настройки читаемости)
`nav-screen-content-after`	Мобильное меню: `ExportButton` + Nolebase
`sidebar-nav-before`	Переключатель дистрибутивов
`doc-before`	Хлебные крошки
`doc-footer-before`	`ReportIssueLink` (ссылка на модалку)
`aside-outline-before`	`ExportButton` (переключатель форматов)
`aside-outline-after`	`ADFootnotesOutline` (сноски рядом с содержанием)
`home-hero-before`	Главная (карточки продуктов) на `layout: home`

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

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

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

yaml

---
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 в проекте документации:

bash

npm install -D pagefind

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

Сжатие изображений

Скриншоты приходят из редакторского пайплайна с тем сжатием, которое выбрал инструмент захвата - как правило, никаким. Повторное кодирование на полном уровне усилий возвращает около двух третей их объёма, пиксель в пиксель.

Это важно дважды: картинки качают читатели, и они же попадают в экспортные бандлы в виде base64, составляя основную массу документа, который получает рендерер PDF.

Замер на одном дистрибутиве:

	до	после
картинки в сборке	51.1 МБ	16.2 МБ
загрузка страницы в chromium	4.6 с	2.3 с
сборка одного PDF	22.3 с	17.2 с
размер PDF	48.2 МБ	39.6 МБ

Сам проход занял 12.8 с на 632 файла.

Сжатие без потерь: это снимки интерфейса с мелким текстом, где кайма, которую оставляет вокруг букв алгоритм с потерями, - ровно то, от чего читатель пытается уйти, увеличивая картинку.

Требуется sharp; без него шаг пропускается с предупреждением, сборка не падает. Настройки - exclude (каталоги), minBytes (порог) и concurrency.

vitepress-theme-alt-docs ​

Установка ​

Подключение ​

Тема (theme/index.ts) ​

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

createSharedConfig(options) ​

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

Layout slots ​

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

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

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

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

Поиск ​

Сжатие изображений ​