> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vuejs/vitepress/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://vitepress.new)

## Installation

<Steps>
  <Step title="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:

    ```bash theme={null}
    node --version
    ```
  </Step>

  <Step title="Install VitePress">
    VitePress can be installed as a development dependency in any project:

    <CodeGroup>
      ```bash npm theme={null}
      npm add -D vitepress@next
      ```

      ```bash pnpm theme={null}
      pnpm add -D vitepress@next
      ```

      ```bash yarn theme={null}
      yarn add -D vitepress@next vue
      ```

      ```bash bun theme={null}
      bun add -D vitepress@next
      ```
    </CodeGroup>

    <Note>
      VitePress is an **ESM-only package**. Make sure your `package.json` contains `"type": "module"`, or use `.mjs`/`.mts` file extensions for your config files.
    </Note>
  </Step>

  <Step title="Run the Setup Wizard">
    VitePress includes an interactive setup wizard to scaffold your project:

    <CodeGroup>
      ```bash npm theme={null}
      npx vitepress init
      ```

      ```bash pnpm theme={null}
      pnpm vitepress init
      ```

      ```bash yarn theme={null}
      yarn vitepress init
      ```

      ```bash bun theme={null}
      bun vitepress init
      ```
    </CodeGroup>

    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
    ```
  </Step>
</Steps>

## 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
```

<Tip>
  The `.vitepress` directory is reserved for VitePress configuration, cache, and build output. Add `.vitepress/cache` and `.vitepress/dist` to your `.gitignore`.
</Tip>

## Understanding the Config File

The config file (`.vitepress/config.js`) controls your site's behavior:

```javascript .vitepress/config.js theme={null}
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' }
    ]
  }
})
```

<Note>
  The `defineConfig` helper provides TypeScript intellisense even in JavaScript files.
</Note>

## Development Commands

The setup wizard adds these npm scripts to your `package.json`:

```json package.json theme={null}
{
  "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:

<CodeGroup>
  ```bash npm theme={null}
  npm run docs:dev
  ```

  ```bash pnpm theme={null}
  pnpm run docs:dev
  ```

  ```bash yarn theme={null}
  yarn docs:dev
  ```

  ```bash bun theme={null}
  bun run docs:dev
  ```
</CodeGroup>

The dev server will start at `http://localhost:5173`. Open this URL in your browser to see your site.

<Warning>
  If port 5173 is already in use, VitePress will automatically try the next available port.
</Warning>

### Build for Production

Generate static HTML for production:

<CodeGroup>
  ```bash npm theme={null}
  npm run docs:build
  ```

  ```bash pnpm theme={null}
  pnpm run docs:build
  ```

  ```bash yarn theme={null}
  yarn docs:build
  ```

  ```bash bun theme={null}
  bun run docs:build
  ```
</CodeGroup>

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

### Preview Production Build

Test your production build locally:

<CodeGroup>
  ```bash npm theme={null}
  npm run docs:preview
  ```

  ```bash pnpm theme={null}
  pnpm run docs:preview
  ```

  ```bash yarn theme={null}
  yarn docs:preview
  ```

  ```bash bun theme={null}
  bun run docs:preview
  ```
</CodeGroup>

The preview server runs at `http://localhost:4173` by default.

## Using VitePress CLI Directly

You can also invoke VitePress commands directly without npm scripts:

<Tabs>
  <Tab title="dev">
    Start the development server:

    ```bash theme={null}
    npx vitepress dev docs
    ```

    Options:

    * `--port <port>`: Specify port number
    * `--host <host>`: Specify hostname
    * `--force`: Force the optimizer to ignore cache
  </Tab>

  <Tab title="build">
    Build for production:

    ```bash theme={null}
    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)
  </Tab>

  <Tab title="preview">
    Preview the production build:

    ```bash theme={null}
    npx vitepress preview docs
    ```

    Options:

    * `--port <port>`: Specify port (default: 4173)
  </Tab>

  <Tab title="init">
    Run the setup wizard:

    ```bash theme={null}
    npx vitepress init
    ```

    Optionally specify the root directory:

    ```bash theme={null}
    npx vitepress init ./my-docs
    ```
  </Tab>
</Tabs>

## Creating Your First Page

Let's create a new documentation page:

<Steps>
  <Step title="Create a new Markdown file">
    Create `docs/getting-started.md`:

    ```markdown docs/getting-started.md theme={null}
    # 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()
    \`\`\`
    ```
  </Step>

  <Step title="Add to navigation">
    Update `.vitepress/config.js` to include your new page:

    ```javascript .vitepress/config.js theme={null}
    export default defineConfig({
      themeConfig: {
        nav: [
          { text: 'Home', link: '/' },
          { text: 'Getting Started', link: '/getting-started' }
        ]
      }
    })
    ```
  </Step>

  <Step title="View your page">
    Navigate to `http://localhost:5173/getting-started` to see your new page.
  </Step>
</Steps>

## Next Steps

Now that you have VitePress running, explore more features:

<CardGroup cols={2}>
  <Card title="File-Based Routing" icon="route" href="./routing">
    Learn how VitePress maps files to URLs and organize your content
  </Card>

  <Card title="Markdown Extensions" icon="markdown" href="/markdown">
    Discover VitePress's powerful Markdown features and syntax
  </Card>

  <Card title="Theme Configuration" icon="palette" href="/theme-config">
    Customize the default theme to match your brand
  </Card>

  <Card title="Deploy Your Site" icon="upload" href="./deploying">
    Learn how to deploy your site to production
  </Card>
</CardGroup>

## Troubleshooting

### ESM Module Errors

If you see errors like `require() of ES Module not supported`, add this to `package.json`:

```json package.json theme={null}
{
  "type": "module"
}
```

Or rename your config file from `.vitepress/config.js` to `.vitepress/config.mjs`.

### Port Already in Use

Specify a different port:

```bash theme={null}
npx vitepress dev docs --port 3000
```

### Cache Issues

Clear the cache and restart:

```bash theme={null}
rm -rf .vitepress/cache
npm run docs:dev
```