Introduction to VitePress
VitePress is a static site generator for documentation, built on Vite and Vue 3. It takes a directory of Markdown files and produces a website that is pre-rendered at build time, hydrated on the client only where interaction is needed, and deployable to any static host. The tool is maintained by the Vue core team and is what the Vue, Vite, and Vitest documentation sites are built with, so the level of polish in the default theme reflects a site that has to serve a large, real project rather than a demo.
Understanding four pieces explains most of what you will encounter when using it.
Vite provides the build and the dev server. This is the single most important fact about VitePress for a newcomer: the local server starts in about a second and hot-updates a single page without a full browser reload, because Vite’s dev server tracks the module graph and only re-transforms what changed. A documentation site is edited constantly, so the speed of that loop determines how pleasant it is to write documentation at all.
Vue 3 provides the component model and, when needed, the client-side runtime. The important nuance is that Vue is not mandatory in the output. A page that contains only prose, code blocks, and images is rendered to static HTML at build time and ships no client-side framework code. Vue enters the picture only on pages that actually use a component, and even then it is loaded as a small chunk.
markdown-it does the Markdown parsing, with a set of VitePress-specific plugins layered on top: custom containers, code groups, snippet imports, GitHub-flavored alerts, and the line-highlighting annotations described later in this chapter.
Shiki does the syntax highlighting. It is the same highlighter that powers the VS Code documentation site, which is why the output looks like a modern editor rather than like a 2005 blog. Because Shiki is a TextMate-grammar engine, the set of supported languages is very large and the themes can be swapped for light and dark mode independently.
| Capability | How VitePress does it |
|---|---|
| Development preview | Vite dev server with hot module replacement |
| Production output | Pre-rendered static HTML plus optional client chunks |
| Markdown parsing | markdown-it with custom plugins |
| Code highlighting | Shiki, with separate light and dark themes |
| Search | Local, client-side index generated at build time |
| Theming | CSS custom properties on the default theme |
| Extension points | Vue components, layout slots, Vite config, build hooks |
The default theme is not a starting point that you are expected to replace; it is a finished documentation site. Out of the box it provides a top navigation bar, a collapsible sidebar, an “on this page” outline derived from the headings, a local search dialog, dark mode with a persisted preference, previous/next page links, an edit-this-page link, and a footer. Local search in particular is worth calling out: it is a static index built during the build and queried in the browser, so it needs no hosted service, no API key, and no per-query cost, and it works even on a documentation site served from a private network.
Because the theme is built on CSS custom properties, restyling it is a matter of overriding variables rather than fighting selectors. Branding a site usually means changing a handful of colour variables and a font stack, which is a small enough job that most projects never need to write a custom theme.
VitePress fits well when the documentation is written by developers who are already comfortable with a JavaScript toolchain, when the site is expected to be fast and searchable, and when the team wants the framework to be invisible. It fits particularly well when the surrounding project is in the Vue ecosystem, because the same skills, the same package manager workflow, and the same component model then apply to both the product and its documentation.
It is a weaker fit when the documentation is authored by people who will never run a local development environment, or when the site genuinely needs server-side rendering for every page. It is also a weaker fit if the project has no JavaScript toolchain at all and introducing one would be the largest single change in the plan — in that case a Python-based generator such as MkDocs is a smaller step.
The smallest useful VitePress site is a config file and one page. The configuration lives in a dot-prefixed directory inside the source folder, which is excluded from routing so that the configuration itself never becomes a page:
my-docs/
├── docs/
│ ├── .vitepress/
│ │ └── config.mts
│ ├── guide/
│ │ └── index.md
│ └── index.md
└── package.json
The configuration file exports a single object. Options that apply to the site as a whole sit at the top level, and options that belong to the theme are nested under themeConfig:
// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'
export default defineConfig({
title: 'My Docs',
description: 'Documentation for the thing I built.',
themeConfig: {
nav: [{ text: 'Guide', link: '/guide/' }],
sidebar: [
{
text: 'Guide',
items: [{ text: 'Introduction', link: '/guide/' }]
}
]
}
})
The split between the two halves of the configuration is a direct expression of the layering described in the previous chapter: the top level is the generator’s business — the site title, the base URL, where the pages live, whether the build should fail on a dead link — while themeConfig is the theme’s business — the navigation, the sidebar, the search options, the footer.
That structure is worth pausing on, because it explains a common source of confusion. If you search for an option in the documentation and cannot find it under themeConfig, it is probably a generator option and belongs at the top level, and vice versa. The next pages work through the setup, the configuration, the Markdown features, and the deployment in turn, and they assume the mental model described here.
