CI/CD for VitePress

Overview

Continuous Integration and Continuous Deployment (CI/CD) automates the process of building, testing, and deploying your VitePress documentation site. This guide covers how to set up CI/CD pipelines for VitePress projects across various platforms.

GitHub Actions

GitHub Actions is a popular choice for CI/CD with VitePress projects.

Basic Workflow

Create a file at .github/workflows/deploy.yml:

name: Deploy VitePress site

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 16
          cache: npm
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build
        run: npm run docs:build
      
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/.vitepress/dist

Caching for Faster Builds

Improve build times with caching:

steps:
  # ... other steps
  - name: Setup Node.js
    uses: actions/setup-node@v3
    with:
      node-version: 16
      cache: npm
  
  - name: Cache .vitepress
    uses: actions/cache@v3
    with:
      path: docs/.vitepress/.cache
      key: ${{ runner.os }}-vitepress-${{ hashFiles('**/package-lock.json') }}
      restore-keys: |
        ${{ runner.os }}-vitepress-

Pull Request Previews

Set up preview deployments for pull requests:

name: PR Preview

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 16
          cache: npm
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build
        run: npm run docs:build
      
      - name: Deploy Preview
        uses: rossjrw/pr-preview-action@v1
        with:
          source-dir: docs/.vitepress/dist

GitLab CI/CD

For GitLab repositories, create a .gitlab-ci.yml file:

image: node:16

cache:
  paths:
    - node_modules/
    - docs/.vitepress/.cache/

stages:
  - build
  - deploy

build:
  stage: build
  script:
    - npm ci
    - npm run docs:build
  artifacts:
    paths:
      - docs/.vitepress/dist

pages:
  stage: deploy
  script:
    - mv docs/.vitepress/dist public
  artifacts:
    paths:
      - public
  only:
    - main

Azure DevOps

For Azure DevOps, create an azure-pipelines.yml file:

trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: NodeTool@0
  inputs:
    versionSpec: '16.x'
  displayName: 'Install Node.js'

- script: |
    npm ci
    npm run docs:build
  displayName: 'Build VitePress site'

- task: CopyFiles@2
  inputs:
    sourceFolder: 'docs/.vitepress/dist'
    contents: '**'
    targetFolder: '$(Build.ArtifactStagingDirectory)'
  displayName: 'Copy build output'

- task: PublishBuildArtifacts@1
  inputs:
    pathToPublish: '$(Build.ArtifactStagingDirectory)'
    artifactName: 'site'
  displayName: 'Publish artifacts'

Netlify

netlify.toml Configuration

Create a netlify.toml file in your project root:

[build]
  publish = "docs/.vitepress/dist"
  command = "npm run docs:build"

[build.environment]
  NODE_VERSION = "16"

# Redirect and rewrite rules
[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200
  
# Headers for caching and security
[[headers]]
  for = "/_assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

Build Hooks

Set up build hooks in Netlify to trigger builds when content changes:

1. Go to Site settings > Build & deploy > Build hooks
2. Create a new build hook
3. Use the webhook URL in your CMS or content repository

Vercel

vercel.json Configuration

Create a vercel.json file:

{
  "buildCommand": "npm run docs:build",
  "outputDirectory": "docs/.vitepress/dist",
  "framework": "vitepress",
  "headers": [
    {
      "source": "/_assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    }
  ]
}

AWS Amplify

amplify.yml Configuration

Create an amplify.yml file:

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm ci
    build:
      commands:
        - npm run docs:build
  artifacts:
    baseDirectory: docs/.vitepress/dist
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*
      - docs/.vitepress/.cache/**/*

Testing in CI/CD

Adding Automated Tests

Include tests in your CI/CD pipeline:

# In GitHub Actions workflow
jobs:
  test-and-deploy:
    runs-on: ubuntu-latest
    steps:
      # ... checkout and setup steps
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test
      
      - name: Build
        run: npm run docs:build
      
      # ... deployment steps

Link Checking

Add link validation to your pipeline:

- name: Check for broken links
  run: npx broken-link-checker --recursive --ordered --exclude-external https://localhost:3000

Best Practices

1. Environment Variables: Store sensitive information (like API keys) as environment variables in your CI/CD platform.

2. Branch Protection: Enable branch protection rules to ensure code quality before merging to main.

3. Automated Testing: Include tests for custom components and functionality.

4. Preview Deployments: Set up preview deployments for pull requests to validate changes before merging.

5. Caching: Implement caching strategies to speed up builds.

6. Notifications: Configure notifications for build failures and successful deployments.

7. Scheduled Builds: Set up periodic builds to ensure external content and links remain valid.

Frequently Asked Questions

How can I deploy to a custom domain?

Most CI/CD platforms support custom domains. For example, with GitHub Pages:

1. Add your custom domain to the repository settings
2. Create a CNAME file in your public directory with your domain name
3. Configure DNS settings with your domain provider

How do I handle environment-specific configurations?

Use environment variables and conditional configuration:

// .vitepress/config.js
export default {
  title: 'My Docs',
  description: process.env.VITE_DESCRIPTION || 'Default description',
  base: process.env.BASE_URL || '/',
  // ...
}

Can I run partial builds to improve CI/CD performance?

VitePress doesn't support partial builds natively, but you can:

1. Use caching effectively
2. Split your documentation into multiple VitePress instances for very large projects
3. Implement custom build scripts that only build changed files (requires custom setup)

Related Resources

• VitePress Official Documentation
• Vue.js Official Documentation
• More Tutorials

---

This document will be continuously updated. If you have any questions, please provide feedback through GitHub Issues.