Getting Started


VuePress v2 is currently in RC (Release Candidate) stage. It's ready to be used for building your site, but the config and API are not stable enough, which is possibly to have minor breaking changes. So make sure to read the changelogopen in new window carefully each time you upgrade a RC version.

Try It Online

You can try VuePress directly in your browser on StackBlitzopen in new window.




Project Setup

Setup via CLI

You can use create-vuepressopen in new window 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/

Directory Structure

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

├─ docs
│  ├─ .vuepress
│  │  └─ config.js
│  └─
└─ 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.

Example `.gitignore` file
# VuePress default temp directory
# VuePress default cache directory
# VuePress default build output directory

Work with VuePress

Start Dev Server

You can add some scriptsopen in new window 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:8080open in new window. 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.