vitepress-plugin-single-page

Build-time Vite-плагин: для каждой версии документации генерирует single.md — все главы версии, склеенные в одну предрендеренную страницу. Зачем:

• Ctrl+F по всему документу — мгновенно, без N клиентских запросов.
• Pagefind (или другой статический поиск) индексирует версию как единый документ.
• Открытие — обычная статическая HTML-страница: ни iframe, ни JS-водопада.

Установка

npm install -D @ampernic/vitepress-plugin-single-page

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

// .vitepress/config.ts
import { defineConfig } from 'vitepress'
import { SinglePagePlugin } from '@ampernic/vitepress-plugin-single-page'

export default defineConfig({
  vite: {
    plugins: [
      SinglePagePlugin({ distroName: 'alt-server' }),
    ],
  },
})

Каждая директория версии под docs/<locale>/ получает single.md, который VitePress собирает в маршрут /<version>/single.

Опции

Опция	Тип	По умолчанию	Описание
srcDir	string	'docs'	Исходная директория VitePress
locale	string	'ru'	Папка локали внутри srcDir
distroName	string	—	Slug; нужен для поиска .vitepress/sidebars/<distro>/<v>.ts
versionPattern	RegExp	/^(\d+\.\d+(\.\d+)*|p\d+)$/	Какие директории считать версиями
pageName	string	'single'	Имя генерируемого файла
titleTemplate	string	'{distro} {version} — на одной странице'	Шаблон заголовка
frontmatter	object	—	Frontmatter, добавляемый к каждой странице
sidebarOrder	(srcDir, version, options) => string[]	встроенный	Своя функция порядка глав

Как работает

1. На configResolved (до того как VitePress сканирует дерево) плагин обходит директории версий.
2. Для каждой версии читает порядок глав из .vitepress/sidebars/.../<v>.ts (или из sidebarOrder).
3. Склеивает index.md версии и всех глав, переписывая относительные пути ассетов так, чтобы они резолвились от single.md (Vite дедуплицирует ассеты по контент-хэшу).
4. Пишет single.md в дерево до сканера VitePress — страница появляется как обычный маршрут.

Каждой главе присваивается стабильный якорь sp-<slug> (см. singleAnchorId), на который ссылается клиентский ребайнд сайдбара в теме.