How to Set Up and Deploy a VitePress Site to GitHub Pages

Introduction

The author switched to VitePress because it is fun, easy to set up, and works well with GitHub for low‑threshold personal blogging. Even a Vue developer can quickly create a stylish site.

What This Article Covers

It focuses on the setup and configuration steps needed to build and deploy a VitePress site, not on project scaffolding or structure.

Reference Links

Links to a comprehensive Chinese VitePress tutorial, AlbertZhang’s documentation site, GitHub Actions introductory video, Markdown syntax guide, and a technical Bilibili channel.

Create VitePress

Enter your working directory and create a folder, e.g., vitepress-doc .

Navigate into vitepress-doc .

pnpm add -D vitepress

Run the initialization wizard:

pnpm vitepress init

After initialization, add a .gitignore file manually with typical entries:

node_modules
.DS_Store
dist
dist-ssr
cache
.cache
.temp
*.local

Deploy to GitHub

Before pushing, create .github/workflows/deploy.yml in the project root. The following workflow builds the VitePress site and deploys it to GitHub Pages:

# Build VitePress site and deploy to GitHub Pages example workflow
#
name: Deploy VitePress site to Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 8.6.12
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: pnpm
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Install dependencies
        run: pnpm install
      - name: Build with VitePress
        run: |
          pnpm docs:build
          touch .nojekyll
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: .vitepress/dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

If the build fails, edit .github/workflows/deploy.yml and ensure the Actions workflow is enabled. In the repository Settings → Pages → Build and deployment, select the main branch and click Save.

After the workflow succeeds (green check mark appears), the site will be available at https:// .github.io/vitepress-doc/ . If CSS is missing, add a base entry in .vitepress/config.mjs :

import { defineConfig } from 'vitepress'

export default defineConfig({
  base: "/vitepress-doc/",
  title: "My Awesome Project",
  description: "A VitePress Site",
  themeConfig: {
    // ...
  }
})

Commit the changes, push again, and the site should render correctly.

Conclusion

The article provides a concise walkthrough of building a VitePress documentation site and deploying it to GitHub Pages, covering essential configuration, CI/CD setup, and common pitfalls.