Skip to main content

​
Quick Start

Get up and running with VitePress in just a few minutes. This guide will walk you through installation, project setup, and your first dev server.

​
Try It Online

Want to try VitePress before installing? You can experiment directly in your browser: Open VitePress on StackBlitz

​
Installation

1

Prerequisites

Before installing VitePress, ensure you have:
  • Node.js version 18 or higher
  • A package manager (npm, pnpm, yarn, or bun)
  • A text editor (VS Code recommended)
Check your Node version:
node --version
2

Install VitePress

VitePress can be installed as a development dependency in any project:
npm add -D vitepress@next
VitePress is an ESM-only package. Make sure your package.json contains "type": "module", or use .mjs/.mts file extensions for your config files.
3

Run the Setup Wizard

VitePress includes an interactive setup wizard to scaffold your project:
npx vitepress init
The wizard will ask you a few questions:
┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./
│
◇  Where should VitePress look for your markdown files?
│  ./
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◇  Theme:
│  ● Default Theme
│  ○ Default Theme + Customization
│  ○ Custom Theme
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes

​
Project Structure

After running the setup wizard, your project will have this structure: 
.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js          # Configuration file
│  ├─ api-examples.md       # Example API docs page
│  ├─ markdown-examples.md  # Markdown examples
│  └─ index.md              # Homepage
└─ package.json
The .vitepress directory is reserved for VitePress configuration, cache, and build output. Add .vitepress/cache and .vitepress/dist to your .gitignore.

​
Understanding the Config File

The config file (.vitepress/config.js) controls your site’s behavior:
.vitepress/config.js
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Awesome Project',
  description: 'A VitePress Site',
  
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Examples', link: '/markdown-examples' }
    ],
    
    sidebar: [
      {
        text: 'Examples',
        items: [
          { text: 'Markdown Examples', link: '/markdown-examples' },
          { text: 'Runtime API Examples', link: '/api-examples' }
        ]
      }
    ],
    
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
    ]
  }
})
The defineConfig helper provides TypeScript intellisense even in JavaScript files.

​
Development Commands

The setup wizard adds these npm scripts to your package.json:
package.json
{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

​
Start Development Server

Launch the dev server with hot module replacement: 
npm run docs:dev
The dev server will start at http://localhost:5173. Open this URL in your browser to see your site.
If port 5173 is already in use, VitePress will automatically try the next available port.

​
Build for Production

Generate static HTML for production: 
npm run docs:build
Built files will be output to .vitepress/dist by default.

​
Preview Production Build

Test your production build locally: 
npm run docs:preview
The preview server runs at http://localhost:4173 by default.

​
Using VitePress CLI Directly

You can also invoke VitePress commands directly without npm scripts:
Start the development server:
npx vitepress dev docs
Options:
  • --port <port>: Specify port number
  • --host <host>: Specify hostname
  • --force: Force the optimizer to ignore cache

​
Creating Your First Page

Let’s create a new documentation page:
1

Create a new Markdown file

Create docs/getting-started.md:
docs/getting-started.md
# Getting Started

Welcome to my documentation!

## Installation

Install the package:

\`\`\`bash
npm install my-package
\`\`\`

## Usage

Here's a basic example:

\`\`\`javascript
import { myFunction } from 'my-package'

myFunction()
\`\`\`
2

Add to navigation

Update .vitepress/config.js to include your new page:
.vitepress/config.js
export default defineConfig({
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Getting Started', link: '/getting-started' }
    ]
  }
})
3

View your page

Navigate to http://localhost:5173/getting-started to see your new page.

​
Next Steps

Now that you have VitePress running, explore more features:

File-Based Routing

Learn how VitePress maps files to URLs and organize your content

Markdown Extensions

Discover VitePress’s powerful Markdown features and syntax

Theme Configuration

Customize the default theme to match your brand

Deploy Your Site

Learn how to deploy your site to production

​
Troubleshooting

​
ESM Module Errors

If you see errors like require() of ES Module not supported, add this to package.json:
package.json
{
  "type": "module"
}
Or rename your config file from .vitepress/config.js to .vitepress/config.mjs.

​
Port Already in Use

Specify a different port: 
npx vitepress dev docs --port 3000

​
Cache Issues

Clear the cache and restart: 
rm -rf .vitepress/cache
npm run docs:dev

Build docs developers (and LLMs) love

Get started for freeTalk to us