Set up a VitePress Project Locally

This guide explains how to initialize a new VitePress project on your local machine and link it to a GitHub repository. Following these steps ensures your project is ready for development and future deployment.

Prerequisites

Before starting, ensure you have Node.js version 18 or higher installed on your system. You also need one of the following package managers installed: npm, Yarn, pnpm, or Bun.

Step 1: Initialize the Project

Create a new directory for your documentation and navigate into it using your terminal. Replace my-docs with your preferred project name:

mkdir my-docs
cd my-docs

Initialize your project and install VitePress along with your layout plugins using your preferred package manager:

npm

npm init -y
npm add -D vitepress vitepress-plugin-group-icons vitepress-plugin-tabs

Yarn

yarn init -y
yarn add -D vitepress vitepress-plugin-group-icons vitepress-plugin-tabs

pnpm

pnpm init
pnpm add -D vitepress vitepress-plugin-group-icons vitepress-plugin-tabs

Bun

bun init -y
bun add -d vitepress vitepress-plugin-group-icons vitepress-plugin-tabs

Step 2: Run the Setup Wizard

VitePress includes a setup wizard to create the basic structure of your site. Launch the wizard by running the appropriate command:

npm

npx vitepress init

yarn

yarn vitepress init

pnpm

pnpm vitepress init

bun

bun x vitepress init

The wizard will ask several questions to configure your site. For a standard setup, you can follow these suggested options:

Question	Recommended Choice
Where should VitePress initialize the config?	./docs
Site title	Enter the name of your documentation site
Site description	Provide a brief summary of your site
Theme	Default Theme
Use TypeScript	Select "Yes" for type safety (recommended) or "No" for standard JavaScript
Add VitePress scripts to package.json?	Yes

Step 3: Update Configuration

VitePress lets you configure every aspect of your documentation site from a single file. This central hub controls your site title, search engine settings, and the interactive plugins that power your code groups.

Most projects use .vitepress/config.mts located in your .vitepress folder. If your project uses plain JavaScript, you can use .vitepress/config.js instead. Update this file to customize your documentation site.

Example:

import { defineConfig } from "vitepress"
import {
  groupIconMdPlugin,
  groupIconVitePlugin,
} from "vitepress-plugin-group-icons"
import { tabsMarkdownPlugin } from "vitepress-plugin-tabs"
import { navConfig } from "./nav"
import { sidebarConfig } from "./sidebar"

export default defineConfig(
  {
    lang: "en-US",
    title: "My Docs",
    description: "Description of My Docs",

    head: [
      ["link", { rel: "icon", href: "/favicon.ico" }],
      [
        "meta",
        {
          name: "theme-color",
          content: "#ffffff",
          media: "(prefers-color-scheme: light)",
        },
      ],
      [
        "meta",
        {
          name: "theme-color",
          content: "#1b1b1f",
          media: "(prefers-color-scheme: dark)",
        },
      ],
      ["script", { src: "/ts/search.ts" }], // Code found here: /deployments/local/vitepress/customize-search
    ],

    sitemap: {
      hostname: "https://docs.example.com",
    },

    lastUpdated: true,
    metaChunk: true,

    markdown: {
      config(md) {
        md.use(groupIconMdPlugin)
        md.use(tabsMarkdownPlugin)
      },
      toc: {
        level: [1, 2, 3, 4, 5, 6],
      },
    },

    vite: {
      ssr: {
        noExternal: ["vitepress-plugin-tabs"],
      },
      plugins: [
        groupIconVitePlugin({
          customIcon: {
            linux: "logos:linux-tux",
            windows: "logos:microsoft-windows",
            mac: "logos:apple",
          },
          defaultLabels: ["linux", "windows", "mac"],
        }),
      ],
    },

    themeConfig: {
      logo: "/img/logo.webp",
      darkModeSwitchLabel: "Toggle Theme",

      outline: [1, 6],

      search: {
        provider: "local",
      },

      nav: navConfig,

      sidebar: sidebarConfig, // Refer to this guide: /deployments/local/vitepress/multi-sidebar-config

      editLink: {
        pattern:
          "https://github.com/your-github-username/your-github-project/edit/main/docs/:path",
        text: "Edit this page on GitHub",
      },

      socialLinks: [
        { icon: "github", link: "https://github.com/your-github-username" },
        { icon: "npm", link: "https://www.npmjs.com/~your-npm-username" },
        { icon: "youtube", link: "https://www.youtube.com/@your-youtube-handle" },
        { icon: "discord", link: "https://discord.com/users/your-discord-username/" },
        { icon: "x", link: "https://x.com/your-x-username" },
      ],

      footer: {
        message:
          '<a href="https://example.com/privacy/" style="text-decoration: none" aria-label="Privacy">Privacy Policy</a>&nbsp;&nbsp;|&nbsp;&nbsp;<a href="https://example.com/tos/" style="text-decoration: none" aria-label="Terms of Service">Terms of Service</a>',
        copyright: `Copyright © 2021-${new Date().getFullYear()} Example.Com`,
      },
    },
  }
)

Step 4: Verify Local Development

Run the development server to ensure the installation was successful:

npm

npm run docs:dev

Yarn

yarn docs:dev

pnpm

pnpm docs:dev

Bun

bun run docs:dev

Open your browser and navigate to http://localhost:5173 to see your documentation site in action.

Step 5: Link to GitHub

Initialize a local Git repository to prepare your project for GitHub. Start by creating a .gitignore file in the root directory to exclude unnecessary files from being tracked:

touch .gitignore

Add the following lines to your .gitignore file:

node_modules
.vitepress/dist
.vitepress/cache

Initialize the repository and commit your initial setup:

git init
git add .
git commit -m "Initial VitePress setup"

Create a new, empty repository on GitHub. Copy the repository URL and link it to your local project using the following commands:

# Replace <your-repository-url> with your actual GitHub URL
git remote add origin <your-repository-url>
git branch -M main
git push -u origin main