Quick Start

This page takes you from an empty directory to a running documentation site. It assumes you have a current Node.js release and a package manager, and that you are comfortable running commands in a terminal. No prior knowledge of Vue is needed.

Install the package

VitePress is a development dependency, because it runs at build time rather than in your published site:

npm add -D vitepress

The same command works with pnpm, yarn, or bun. The only requirement to be aware of is that VitePress is published as an ESM-only package, so the nearest package.json must contain "type": "module", or the files that import it must use the .mjs or .mts extension. If you forget this, the error you get is a require() of ES Module error pointing at vitepress, and the fix is to add the type field rather than to change the import.

Scaffold the project

VitePress ships a setup wizard that creates the directory structure, the configuration file, and the npm scripts for you:

npx vitepress init

The wizard asks a handful of questions: where the configuration should live, where the Markdown files should live, the site title and description, whether to use TypeScript for the configuration and theme files, and whether to add the VitePress scripts to package.json. Answering them produces a project that looks like this:

my-docs/
├── docs/
│   ├── .vitepress/
│   │   ├── config.mts
│   │   └── theme/
│   │       └── index.ts
│   ├── api-examples.md
│   ├── markdown-examples.md
│   └── index.md
└── package.json

The docs directory is the project root for the site, and the .vitepress directory inside it is reserved for the configuration, the theme override, the dev server cache, and the build output. Nothing inside .vitepress is ever routed to a page.

If you would rather set the project up by hand, the wizard is optional. Add the scripts to package.json:

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

and create the two directories with a configuration file in docs/.vitepress/.

Write the first page

A page is a Markdown file with front matter. The index.md file in the source directory becomes the home page:

---
title: My Project
description: Documentation for the thing I built.
---

# My Project

Welcome to the documentation. Edit `docs/index.md` to change this page.

The docs argument in the scripts above is the source directory. If you scaffold into a different location, change it there and the three commands keep working unchanged.

Run the dev server

npm run docs:dev

The server starts on http://localhost:5173 and reloads content as you save. Because it is built on Vite, saving a Markdown file updates the page in place without a full reload, and saving a component updates only the components that depend on it. This is the loop you will spend most of your time in.

You can also call the CLI directly, which is useful when the project has several sites:

npx vitepress dev docs

Pass a different port if 5173 is already taken — for example npx vitepress dev docs --port 5174.

Build and preview

When you are ready to see what the published site will actually look like, build it and serve the output:

npm run docs:build
npm run docs:preview

The build writes to docs/.vitepress/dist, and the preview command serves that directory on http://localhost:4173. The preview is not identical to the dev server: it serves the real production output, with hashed asset filenames and the pre-rendered pages, so it is the right way to check for broken links and missing assets before publishing. The port can be changed with --port.

Add the generated directories to your .gitignore, because both the dev cache and the build output are disposable:

docs/.vitepress/cache
docs/.vitepress/dist
node_modules

Common problems

SymptomCauseFix
require() of ES Module ... vitepressThe project is CommonJSAdd "type": "module" to package.json
Build fails with a dead linkA link points at a page that does not existFix the link, or configure the build to ignore it
The sidebar is emptyNo sidebar is configuredAdd a sidebar array under themeConfig
Changes do not appearThe dev server is watching a different directoryCheck the path passed to vitepress dev
Page 404s after the buildA base path does not match the hosting pathSet base to the path the site will be served from

What to do next

You now have a running site with a home page, a configuration file, and a dev loop. The natural next steps are to give the site a real information architecture — a navigation bar, a sidebar, and a footer — which is a configuration exercise covered in the next page; to write content using the Markdown features VitePress adds on top of standard Markdown, including callouts, code groups, and imported snippets; and to publish the result, which mostly comes down to running the build and pointing a host at the output directory.

Found an issue with this content?

Tell us what could be improved.