Basics of VitePress

VitePress is a static site generator built on top of Vite and Vue. It is commonly used for documentation, blogs, and content-focused websites.

Installation

Create a project:

pnpm create vitepress

Or install VitePress into an existing project:

pnpm add -D vitepress

Project Structure

A basic VitePress project looks like:

.
├── docs/
│   ├── .vitepress/
│   │   └── config.js
│   ├── index.md
│   └── guide.md
└── package.json

The .vitepress directory contains VitePress configuration.

Start the Development Server

Add a script to package.json:

{
  "scripts": {
    "docs:dev": "vitepress dev docs"
  }
}

Then run:

pnpm docs:dev

Markdown

VitePress pages are written in Markdown:

# Hello

This is a VitePress page.

## Section

Some content here.

Each Markdown file becomes a page.

For example:

docs/guide.md

becomes:

/guide

Frontmatter

Pages can have YAML frontmatter:

---
title: My Page
description: A simple VitePress page
---

# My Page

Configuration

Create .vitepress/config.js:

import { defineConfig } from "vitepress";

export default defineConfig({
  title: "My Docs",
  description: "My documentation",

  themeConfig: {
    nav: [
      { text: "Home", link: "/" },
      { text: "Guide", link: "/guide" },
    ],

    sidebar: [
      {
        text: "Guide",
        items: [{ text: "Introduction", link: "/guide" }],
      },
    ],
  },
});

Navigation

nav controls the top navigation:

nav: [
  { text: "Home", link: "/" },
  { text: "Guide", link: "/guide" },
];

Sidebar

sidebar controls the sidebar:

sidebar: [
  {
    text: "Guide",
    items: [
      { text: "Introduction", link: "/guide" },
      { text: "Installation", link: "/guide/installation" },
    ],
  },
];

Code Blocks

Markdown code blocks are supported:

const message = "Hello";
console.log(message);

VitePress also supports syntax highlighting:

const add = (a: number, b: number) => a + b;

Vue Components

VitePress supports Vue components inside Markdown.

For example:

<script setup>
import { ref } from "vue";

const count = ref(0);
</script>

<button @click="count++">
Count: {{ count }}
</button>

Build

Build the documentation site:

pnpm vitepress build docs

The generated site is placed in:

docs/.vitepress/dist/

Preview

Preview the production build:

pnpm vitepress preview docs

Why Use VitePress?

VitePress is useful when you want:

• Markdown-based documentation
• Fast development with Vite
• Vue components when needed
• Static HTML generation
• Built-in navigation and sidebar support
• Search integration
• A documentation-oriented theme

Basic Workflow

Markdown
   ↓
VitePress
   ↓
Vite
   ↓
Static HTML/CSS/JS
   ↓
Deploy

For a documentation site, most content can simply be written as Markdown while VitePress handles the site structure and build process.