Quick Start

Install VitePress and create your first documentation site

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

   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:

   npm

   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

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

npm run docs:build

Built files will be output to .vitepress/dist by default.

Preview Production Build

Test your production build locally:

npm

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:

dev

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

build

Build for production:

npx vitepress build docs

Options:

• --outDir <dir>: Output directory (default: .vitepress/dist)
• --base <path>: Public base path
• --mpa: Build in MPA mode (multi-page application)

preview

Preview the production build:

npx vitepress preview docs

Options:

• --port <port>: Specify port (default: 4173)

init

Run the setup wizard:

npx vitepress init

Optionally specify the root directory:

npx vitepress init ./my-docs

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