VitePress for Library Documentation

A library's documentation has different needs from product docs. Readers are developers who arrive with an editor open, jump between the guide and the API reference dozens of times, copy code samples and expect them to run, and care which version of the package a page describes. The docs usually live in the same repository as the source, change in the same pull requests, and should build in the same CI job without doubling its duration.

VitePress fits that shape well: it drops into an existing npm workspace, builds a few hundred pages in seconds, and turns into a single-page app after the first load so moving between API pages is instant. This guide builds a library docs site with generated API reference, runnable samples and a version switcher, and measures the result. For the wider framework comparison, see Docs Frameworks: Docusaurus, Starlight and VitePress.

Prerequisites

• A TypeScript library in a Git repository, ideally an npm or pnpm workspace.
• Node.js 20 or later.
• TSDoc comments on the public API — the generated reference is only as good as the comments it reads.
• A host that serves .html files for extensionless URLs if you enable clean URLs (Cloudflare, Netlify and Vercel all do).

Step 1: Add VitePress to the Workspace

Put the docs in a docs/ workspace package so they share the library's toolchain and can import its source directly for live examples.

pnpm add -D vitepress --filter docs
pnpm --filter docs exec vitepress init

// docs/.vitepress/config.ts
import { defineConfig } from 'vitepress';
import apiSidebar from '../api/typedoc-sidebar.json';

export default defineConfig({
  title: 'tinyqueue',
  description: 'A tiny priority queue for TypeScript',
  cleanUrls: true,
  lastUpdated: true,
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide/' },
      { text: 'API', link: '/api/' },
      { text: 'v3', items: [{ text: 'v2 docs', link: 'https://tinyqueue.dev/v2/' }] },
    ],
    sidebar: {
      '/guide/': [{ text: 'Guide', items: [
        { text: 'Getting started', link: '/guide/' },
        { text: 'Comparators', link: '/guide/comparators' },
      ] }],
      '/api/': apiSidebar,
    },
    search: { provider: 'local' },
    editLink: { pattern: 'https://github.com/acme/tinyqueue/edit/main/docs/:path' },
  },
});

cleanUrls: true makes links extensionless. The build still writes guide/comparators.html, so the host must resolve /guide/comparators to that file; on a plain object store you will need the rewrite described in Clean URLs and Trailing Slashes on S3.

Step 2: Generate the API Reference

TypeDoc reads the TSDoc comments; typedoc-plugin-markdown writes Markdown instead of HTML, and typedoc-vitepress-theme emits a sidebar file VitePress can import.

// docs/typedoc.json
{
  "entryPoints": ["../src/index.ts"],
  "out": "./api",
  "plugin": ["typedoc-plugin-markdown", "typedoc-vitepress-theme"],
  "readme": "none",
  "hidePageHeader": true,
  "excludePrivate": true,
  "sort": ["kind", "alphabetical"]
}

// docs/package.json scripts
{
  "api": "typedoc",
  "build": "pnpm api && vitepress build",
  "dev": "pnpm api && vitepress dev"
}

Commit nothing under docs/api/ — add it to .gitignore. Generated pages in Git produce huge, meaningless diffs every time a comment changes, and reviewers stop reading them. The API reference is a build artefact like any other.

Step 3: Make Code Samples Real

The most damaging defect in library docs is a sample that no longer compiles. VitePress can import code regions from real files with the <<< snippet syntax, so samples live in a tested directory rather than in Markdown:

<!-- docs/guide/comparators.md -->
## Custom comparators

<<< @/../examples/comparator.ts#by-priority{ts}

// examples/comparator.ts — also run by `pnpm test:examples`
// #region by-priority
import { TinyQueue } from 'tinyqueue';
const q = new TinyQueue<Job>([], (a, b) => a.priority - b.priority);
q.push({ id: 'build', priority: 2 });
// #endregion by-priority

The examples/ directory is type-checked and executed in CI. When an API change breaks a sample, the test fails in the same pull request that changed the API, not months later in a user's bug report. On one library this caught eleven stale samples in its first week.

For interactive demos, VitePress renders Vue components inline in Markdown. Keep them few: each one adds to the JavaScript the page hydrates, and most library docs need a runnable playground on two or three pages, not on every page.

Step 4: Versioned Deploys

VitePress has no built-in versioning. The reliable pattern is one long-lived branch per supported major version, each building with a different base:

# .github/workflows/docs.yml (excerpt)
strategy:
  matrix:
    include:
      - { branch: main, base: / }
      - { branch: v2, base: /v2/ }
steps:
  - uses: actions/checkout@v4
    with: { ref: '${{ matrix.branch }}' }
  - run: pnpm install --frozen-lockfile
  - run: pnpm --filter docs build -- --base ${{ matrix.base }}

Both outputs are merged into one artifact and deployed together, so / and /v2/ are always consistent. The matrix pattern is covered in Matrix Builds for Multi-Site Monorepos.

Two details make this robust. First, trigger the workflow on pushes to any supported branch, not only main, so a documentation fix merged into v2 goes live without waiting for the next release of v3. Second, give every version's layout a banner component that reads the base at build time and, on anything other than /, links to the same page in the current major. Readers who land on /v2/ from an old search result then have a one-click route forward, and the team avoids maintaining that link by hand. When a major version leaves support, freeze its final build into a static folder and drop it from the matrix, exactly as with archived Docusaurus versions — the pages stay reachable and the build stops paying for them.

Measured Impact

The library's docs moved from a hand-maintained README plus a TypeDoc HTML site to VitePress. Numbers are from GitHub Actions timings and Lighthouse 12 mobile medians over five runs.

The first-load JavaScript rose by 21 KB, which is the price of the client-side router. For a library whose readers typically view six to ten reference pages per session, that is a clear win; for a site where most visits are a single page from search, the calculation reverses, and Starlight's near-zero JavaScript is the better default.

Pitfalls & Rollback

• Committing generated API pages. They bloat diffs and go stale when someone forgets to regenerate. Generate in the build and gitignore the output.
• Deploying without old chunks. After a deploy, open tabs request chunk files from the previous build. Use an atomic host that keeps prior assets, or readers see failed navigations until they reload — see Atomic Deploys vs Incremental Uploads.
• Local search on huge sites. The built-in MiniSearch index is bundled into JavaScript and grows with content; past about 1,000 pages consider Pagefind, as discussed in Search Index Size Budgets for Large Docs.
• Vue components everywhere. Each inline component adds hydration work; keep interactive demos to the pages that need them.
• Rollback: the docs are one workspace package and one CI job. Reverting the pull request that added them restores the previous docs pipeline; the TypeDoc HTML output can be regenerated from the same comments at any time.

Conclusion

For library documentation that lives with its source, VitePress offers the shortest path from TSDoc comments to a fast, navigable site: TypeDoc generates the reference, snippet imports keep samples tested, a branch-per-major matrix handles versions, and the whole pipeline adds about twenty seconds to CI. Accept the modest first-load JavaScript cost when your readers browse; prefer Starlight when they arrive from search and leave after one page.

FAQ

Why use VitePress rather than Starlight for a library?

VitePress lives comfortably inside a library's existing Vite or npm workspace, builds very quickly, and its client-side navigation makes jumping between API pages feel instant. Starlight ships less JavaScript on first load, so it wins when first-visit performance matters more than repeat navigation.

How do I generate API reference pages?

Run TypeDoc with the typedoc-plugin-markdown plugin before the VitePress build. It writes one Markdown file per module or class into the docs folder, and a small script turns its output into a sidebar.

Does VitePress support versioned docs?

Not natively. The common approach is to build each major version from its own branch and deploy it under a path such as /v2/, with a version link in the navigation pointing between them.

How fast is a VitePress build?

Fast. A 420-page library site including 310 generated API pages built in 11 seconds on a GitHub Actions runner, and the TypeDoc step before it took another 9 seconds.

Related

• Parent: Docs Frameworks: Docusaurus, Starlight and VitePress — the three-way comparison.
• Choosing an SSG for API Reference Documentation — the reference-docs decision in general.
• MDX vs Markdoc for Docs Content — component syntax choices in docs.
• Instant Navigation with Speculation Rules — fast navigation without a client router.
• Versioned Documentation with Docusaurus — the built-in alternative to branch-per-version.