vitepress-theme-alt-docs

Shared VitePress theme for ALT Linux documentation. Combines every package of the monorepo into a ready-to-use configuration.

Installation

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

The theme pulls the other packages in as dependencies automatically.

Wiring

Theme (theme/index.ts)

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

Config (.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: 'Russian', ...ru },
  },
})

createSharedConfig(options)

Option	Type	Default	Description
distroName	string	-	Distribution slug (e.g. 'alt-server'). Required
productName	string	-	Display name of the product. Wired into the PWA manifest, <title>, LLM output
allDistros	string[]	-	List of every distribution shown in the switcher. distros.json next to the config wins over the option
sections	SectionInfo[]	-	Distribution groupings in the switcher; sections.json next to the config wins
productLinks	Record<string, string>	-	Slug -> external product page. The current distribution link is fed to export.logoLink automatically
hostname	string	-	Absolute hostname used for sitemap, canonical, og:image
editLinkRepo	string	alt-docs/docs-vitepress	Forgejo repository for the "Suggest an edit" button
export	ExportPluginOptions	-	Options for PDF / HTML / EPUB export. When absent, no export runs
meta	MetaPluginOptions | false	defaults	SEO / OG / canonical. false disables MetaPlugin entirely
llms	LlmsPluginOptions | false	defaults	llms.txt / llms-full.txt / per-page mirror. false disables
singlePage	Omit<SinglePagePluginOptions, 'distroName'>	-	Single-page options (e.g. dropInitialTOC: true)
reportIssue	false | { repo?; origin?; labels?; shortcut? }	alt-docs/docs-vitepress	Ctrl+Enter -> Forgejo new issue. false disables
optimizeImages	boolean | OptimizeImagesOptions	on	Losslessly recompresses PNGs in the built site before the export bundles inline them. false skips it
debug	boolean	false	Single flag that enables debug in every nested plugin (a nested debug option still wins over it)

Bundled plugins

Plugin	What it gives you
vitepress-plugin-pagefind	Pagefind search filtered by version
vitepress-alt-docs-versioning	Version and edition switcher
vitepress-plugin-breadcrumbs	Breadcrumbs above the content
vitepress-plugin-cross-site-router	Cross-site navigation
vitepress-plugin-single-page	Single-page view of a version
vitepress-plugin-export	Version export to PDF / HTML / EPUB
vitepress-plugin-html-image	Normalizes <img> in raw HTML
vitepress-plugin-meta	Canonical, sitemap, Open Graph, OG image
vitepress-plugin-llms	llms.txt, llms-full.txt, per-page markdown mirror
vitepress-plugin-report-issue	Ctrl+Enter -> pre-filled Forgejo issue
alt-docs-registry	Shared distribution registry (products.yaml)
@nolebase/vitepress-plugin-enhanced-readabilities	Content width switcher
vitepress-plugin-tabs	Tabs in Markdown
markdown-it-kbd	<kbd> syntax
markdown-it-attrs	{#id .class} after headings
@alt-gnome/markdown-it-custom-containers	Containers left, center, right

Layout slots

The theme occupies the following VitePress slots:

Slot	Component
layout-top	ReportIssueDialog ("Report a problem" modal)
nav-bar-content-before	Search bar (button + modal)
nav-bar-content-after	Nolebase menu (readability settings)
nav-screen-content-after	Mobile menu: ExportButton + Nolebase
sidebar-nav-before	Distribution switcher
doc-before	Breadcrumbs
doc-footer-before	ReportIssueLink (link that opens the modal)
aside-outline-before	ExportButton (format switcher)
aside-outline-after	ADFootnotesOutline (footnotes next to the outline)
home-hero-before	Landing (product cards) on layout: home

Landing and index pages

Landing (layout: home)

The landing (index site) uses layout: home; the content is rendered by theme components driven by frontmatter altHome:

---
layout: home
altHome:
  hero:
    logo: basealt
    title: BaseALT Documentation
    text: Official documentation of the ALT operating system.
  products:
    alt-server:
      tagline: Complete server solution for IT infrastructure
      accent: '#8e96a3'
      grad: ['#c8d0dd', '#8e96a3']
  footer:
    links:
      - { title: Company site, url: https://www.basealt.ru/ }
    copyright: (c) 2026 BaseALT
---

The list of distributions and sections comes from __VERSIONS_DATA__ (the versioning plugin); altHome.products[<slug>] sets the tagline and accent color of the card (the default name comes from the shared registry).

Distribution landing

The distribution landing template renders <VersionList distro="<slug>" />, releases grouped by major version, cards with lists and an "Actual" badge.

Content layout

The theme expects files at docs/ru/{version}/... with the rewrite rule ru/:slug* -> :slug*.

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

Search

Search only works in the production build. pagefind must be installed as a devDependency of the docs project for indexing:

npm install -D pagefind

After vitepress build, pagefind --site .vitepress/dist runs automatically. Search is filtered by the current page version.

Image recompression

Screenshots arrive from the authoring pipeline at whatever compression the capture tool chose, which is usually none. Re-encoding at full effort returns about two thirds of their bytes, pixel for pixel.

That matters twice over: readers download these, and the export bundles inline them as base64, where they make up the bulk of the document handed to the PDF renderer.

Measured on one distribution:

	before	after
images in the build	51.1 MB	16.2 MB
page load in chromium	4.6 s	2.3 s
building one PDF	22.3 s	17.2 s
PDF size	48.2 MB	39.6 MB

The pass itself took 12.8 s over 632 files.

Lossless on purpose: these are UI screenshots full of small text, where the ringing a lossy codec leaves around glyphs is exactly what a reader zooms in to escape.

Requires sharp; without it the step is skipped with a warning rather than failing the build. Tunables are exclude, minBytes and concurrency.