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.

How it fits together

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.

CapabilityHow VitePress does it
Development previewVite dev server with hot module replacement
Production outputPre-rendered static HTML plus optional client chunks
Markdown parsingmarkdown-it with custom plugins
Code highlightingShiki, with separate light and dark themes
SearchLocal, client-side index generated at build time
ThemingCSS custom properties on the default theme
Extension pointsVue components, layout slots, Vite config, build hooks

What the default theme gives you

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.

When VitePress is the right choice

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.

A minimal site

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.

Found an issue with this content?

Tell us what could be improved.