vitepress-plugin-export

Генерация экспортных файлов документации (PDF, HTML, EPUB) после vitepress build. Плагин обходит все страницы версий из сайдбара, собирает единый документ с оглавлением и сохраняет результат в директорию dist.

Что умеет:

• Генерирует PDF через Chromium/Chrome с точными закладками (использует named destinations из PDF, созданные Chrome)
• Генерирует автономный HTML с инлайновым CSS
• Генерирует EPUB 3 с иерархическим оглавлением и работающими внутренними ссылками
• Определяет версии автоматически по ключам сайдбара (/11.2/, /11.1/ и т.д.)
• Пишет export-manifest.json для компонента ExportButton в теме
• Раздаёт готовые файлы через dev-сервер VitePress

Установка

pnpm add -D @ampernic/vitepress-plugin-export

Для PDF нужен Chromium или Chrome в системе. Для PDF также требуется puppeteer-core:

pnpm add -D puppeteer-core

Для EPUB нужен jszip:

pnpm add jszip

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

Через createSharedConfig (рекомендуется)

При использовании @ampernic/vitepress-theme-alt-docs достаточно передать опцию export:

// .vitepress/config/index.mts
import { createSharedConfig } from '@ampernic/vitepress-theme-alt-docs/config'
import { sidebar } from './sidebar'

const shared = createSharedConfig({
  distroName: 'alt-kworkstation',
  export: {
    sidebar,
    distroName: 'alt-kworkstation',
    formats: ['pdf', 'html', 'epub'],
    tocDepth: 2,
  },
})

Напрямую в VitePress config

// .vitepress/config.mts
import { defineConfig } from 'vitepress'
import { ExportPlugin } from '@ampernic/vitepress-plugin-export'
import { sidebar } from './sidebar'

const exportPlugin = ExportPlugin({
  sidebar,
  distroName: 'alt-kworkstation',
  formats: ['pdf', 'html', 'epub'],
})

export default defineConfig({
  buildEnd: async () => {
    await exportPlugin.buildEnd()
  },
  vite: {
    plugins: [...exportPlugin.vite.plugins],
  },
})

Опции

Опция	Тип	По умолчанию	Описание
sidebar	SidebarMulti	—	Сайдбар VitePress (обязательно)
distroName	string	—	Slug дистрибутива, используется в именах файлов
formats	('pdf' | 'html' | 'epub')[]	['pdf']	Форматы для генерации
versions	string[]	авто	Версии; если не указано — берутся из ключей сайдбара
outDir	string	.vitepress/dist	Директория собранного сайта
base	string	из Vite	Base URL сайта
executablePath	string	из env/системы	Путь к Chromium/Chrome (для PDF)
skip	boolean	false	Пропустить генерацию (удобно в dev)
tocDepth	number	2	Максимальная глубина оглавления
waitUntil	string	'load'	Puppeteer waitUntil (для PDF)
pagesLimit	number	—	Лимит страниц на версию (для отладки)
debug	boolean	false	Подробный лог

Именование файлов

Файлы сохраняются в корень outDir:

• {distroName}-{version}.pdf — например alt-kworkstation-11.2.pdf
• {distroName}-{version}.html — например alt-kworkstation-11.2.html
• {distroName}-{version}.epub — например alt-kworkstation-11.2.epub

Если distroName не указан: export-{version}.pdf и т.д.

Компонент кнопки скачивания

Плагин включает Vue-компонент ExportButton, который читает export-manifest.json и показывает выпадающее меню для скачивания. В теме vitepress-theme-alt-docs он подключён автоматически в слот aside-outline-after.

Для ручного подключения:

// .vitepress/theme/index.ts
import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import ExportButton from '@ampernic/vitepress-plugin-export/components/ExportButton.vue'

export default {
  extends: DefaultTheme,
  Layout() {
    return h(DefaultTheme.Layout, null, {
      'aside-outline-after': () => h(ExportButton),
    })
  },
}

Как работает PDF

1. Все страницы версии объединяются в один HTML-документ с оглавлением
2. Документ открывается в Chromium через Puppeteer и печатается в PDF
3. После генерации PDF считываются GoTo-аннотации (named destinations), которые Chrome создал для ссылок оглавления
4. Из этих аннотаций строится иерархическое дерево закладок (outline) и вставляется в PDF через pdf-lib

Хромиум

Плагин ищет Chromium в порядке:

1. executablePath в опциях
2. PUPPETEER_EXECUTABLE_PATH env
3. Стандартные системные пути (/usr/bin/chromium-browser, /usr/bin/google-chrome и т.д.)