Getting Started

Try It Online

You can try VuePress directly in your browser on StackBlitz.

Installation

Prerequisites

• Node.js v20.6.0+
• Package manager like pnpm, yarn, npm, etc.

Project Setup

Setup via CLI

You can use create-vuepress to generate a template directly.

pnpm create vuepress vuepress-starter

yarn create vuepress vuepress-starter

npm init vuepress vuepress-starter

Setup Manually

This section will help you build a basic VuePress documentation site from ground up.

• Create and change into a new directory

mkdir vuepress-starter
cd vuepress-starter

• Initialize your project

git init
pnpm init

git init
yarn init

git init
npm init

• Install VuePress

# install vuepress and vue
pnpm add -D vuepress@next vue
# install bundler and theme
pnpm add -D @vuepress/bundler-vite@next @vuepress/theme-default@next

# install vuepress
yarn add -D vuepress@next
# install bundler and theme
yarn add -D @vuepress/bundler-vite@next @vuepress/theme-default@next

# install vuepress
npm install -D vuepress@next
# install bundler and theme
npm install -D @vuepress/bundler-vite@next @vuepress/theme-default@next

• Create docs directory and docs/.vuepress directory

mkdir docs
mkdir docs/.vuepress

• Create the VuePress config file docs/.vuepress/config.js

import { viteBundler } from '@vuepress/bundler-vite'
import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  bundler: viteBundler(),
  theme: defaultTheme(),
})

• Create your first document

echo '# Hello VuePress' > docs/README.md

Directory Structure

After the setup, the minimal structure of your project should look like this:

├─ docs
│  ├─ .vuepress
│  │  └─ config.js
│  └─ README.md
└─ package.json

The docs directory is where you put your markdown files, and it will be used as the source directory of VuePress.

The docs/.vuepress directory, i.e. the .vuepress directory in the source directory, is where all VuePress-specific files will be placed. Currently there is only one config file in it. By default, the temp, cache and output directory will also be generated inside this directory. It is suggested to add them to your .gitignore file.

# VuePress default temp directory
.vuepress/.temp
# VuePress default cache directory
.vuepress/.cache
# VuePress default build output directory
.vuepress/dist

Work with VuePress

Start Dev Server

You can add some scripts to package.json:

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

Then, run docs:dev script to start the dev server:

pnpm docs:dev

yarn docs:dev

npm run docs:dev

VuePress will start a hot-reloading development server at http://localhost:8080. When you modify your markdown files, the content in the browser will be auto updated.

Build Your Site

To build your site, run docs:build script:

pnpm docs:build

yarn docs:build

npm run docs:build

You will see the generated static files in the docs/.vuepress/dist directory. You can check out deployment for how to deploy them.

Learn More about VuePress

By now, you should have a basic but functional VuePress site. But you may still need to read the subsequent guide to learn more about VuePress.

Next step, learn more about the configuration.