4.2 KiB

Raw Blame History

Getting Started

Prerequisites

VitePress requires Node.js version 16 or higher.

Installation

VitePress can be used on its own, or be installed into an existing project. Either way, you can install it with:

::: code-group

$ npm install -D vitepress

$ pnpm add -D vitepress

$ yarn add -D vitepress

:::

::: details Getting missing peer deps warnings? If using PNPM, you will notice a missing peer warning for @docsearch/js. This does not prevent VitePress from working. If you wish to suppress this warning, add the following to your package.json:

"pnpm": {
  "peerDependencyRules": {
    "ignoreMissing": [
      "@algolia/client-search"
    ]
  }
}

:::

Setup Wizard

VitePress ships with a command line setup wizard that will help you scaffold a basic project. Start the wizard by running:

$ npx vitepress init

You should be greeted with the following:

vitepress init screenshot

If you are installing VitePress in an existing project alongside the source code, it is recommended to scaffold the site in a nested directory so that it is separate from the rest of the project.

File Structure

Assuming you chose to scaffold the VitePress project in ./docs, the generated file structure should look like this:

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

The docs directory is considered the project root of the VitePress site. The .vitepress directory contains the config file, dev server cache, build output, and optional theme customization code.

The Config File

The config file allows you to customize various aspects of your VitePress site, with the most basic options being the title and description of the site:

// .vitepress/config.js
export default {
  // site-level options
  title: 'VitePress',
  description: 'Just playing around.',

  themeConfig: {
    // theme-level options
  }
}

You can also configure the behavior of the theme via the themeConfig option. Consult the Site Config Reference for full details on all config options.

Source Files

Markdown files outside the .vitepress directory are considered source files.

VitePress uses file-based routing: each .md file is compiled into a corresponding .html file with the same path. For example, index.md will be compiled into index.html, and can be visited at the root path / of the resulting VitePress site.

We will discuss more about Routing in the next chapter.

Up and Running

The tool should have also injected the following npm scripts to your package.json if you allowed it to do so during the setup process:

{
  ...
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  ...
}

The docs:dev script will start a local dev server with instant hot updates. Run it with the following command: