vitepress-export

Export a VitePress documentation site to a publication-grade PDF with correct global page numbering, cross-referenced Table of Contents, running headers/footers, and first-class CJK typography.

Quick start

# Export an online VitePress site — no installation needed
npx vitepress-export pdf --serve https://example.com

# Or from a local project (auto build + preview)
cd /path/to/vitepress-project
npx vitepress-export pdf

Output defaults to vitepress-export.pdf.

CLI

vitepress-export pdf [options]

| Option | Description | Default | | ----------------------- | -------------------------------- | ---------------------- | | -c, --config <path> | Explicit config file | discovery | | --root <path> | VitePress project root | cwd | | --preset <name> | Typography preset | default | | -o, --output <file> | Output path | vitepress-export.pdf | | --serve <url> | Connect to an existing server | — | | --format <A4\|Letter> | Page format | A4 | | --origin <url> | Public origin URL for assets | — | | --no-cache | Skip disk cache, re-scrape pages | off | | --debug | Verbose debug logging | off |

Usage

Auto-start preview (default)

Runs vitepress build then vitepress preview automatically.

vitepress-export pdf

Connect to an existing server

Point to a running vitepress preview or vitepress dev server, or a remote VitePress site.

# Terminal 1: start preview
pnpm vitepress preview

# Terminal 2: export
vitepress-export pdf --serve http://localhost:4173

Configuration

Create export.config.ts in your VitePress project root (or .vitepress/):

import { defineExportConfig } from "vitepress-export";

export default defineExportConfig({
  output: "my-doc.pdf",
  headerFooter: {
    enabled: true,
    footer: { center: "Page {page} / {total}" },
  },
  typography: {
    cjkLatinSpacing: true,
    avoidHeadTail: true,
    punctuationCompression: true,
  },
});

Config discovery order (highest priority first):

1. --config <path> (explicit)
2. <root>/.vitepress/export.config.ts
3. <root>/export.config.ts
4. Walk up from cwd
5. Built-in defaults

A usable config can be found in docs/.vitepress/export.config.ts.

Pipeline

VitePress HTML pages
    ↓  scrape .VPSidebar DOM → ordered route list
router/
    ↓  per-page scrape, strip chrome, concatenate
assembler/  →  long static HTML (663 KB for 65 routes)
    ↓  load in Playwright, inject Paged.js
renderer/   →  fragment into paged layout, page.pdf()
    ↓  pdf-lib: metadata, watermark(beta)
postprocess/
    ↓
publication-grade PDF

Requirements

• Node.js 22+
• Chromium — probes system Chrome first; install via npx playwright install chromium if missing
• VitePress 1+ project

License

MIT