deployment.md

Deployment

The following guides are based on some shared assumptions:

• You are placing your Markdown source files inside the docs directory of your project;
• You are using the default build output location (.vuepress/dist);
• You are using pnpm as package manager, while npm and yarn are also supported;
• VuePress is installed as a local dependency in your project, and you have setup the following script in package.json:

{
  "scripts": {
    "docs:build": "vuepress build docs"
  }
}

GitHub Pages

1. Set the correct base config.

   If you are deploying to https://<USERNAME>.github.io/, you can omit this step as base defaults to "/".

   If you are deploying to https://<USERNAME>.github.io/<REPO>/, for example your repository is at https://github.com/<USERNAME>/<REPO>, then set base to "/<REPO>/".

2. Choose your preferred CI tools. Here we take GitHub Actions as an example.

   Create .github/workflows/docs.yml to set up the workflow.

::: details Click to expand sample config

name: docs

on:
  # trigger deployment on every push to main branch
  push:
    branches: [main]
  # trigger deployment manually
  workflow_dispatch:

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6
        with:
          # fetch all commits to get last updated time or other git log info
          fetch-depth: 0

      - name: Setup pnpm
        uses: pnpm/action-setup@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          # choose node.js version to use
          node-version: 24
          # cache deps for pnpm
          cache: pnpm

      - name: Install deps
        run: pnpm ci

      # run build script
      - name: Build VuePress site
        run: pnpm docs:build

      # please check out the docs of the workflow for more details
      # @see https://github.com/crazy-max/ghaction-github-pages
      - name: Deploy to GitHub Pages
        uses: crazy-max/ghaction-github-pages@v4
        with:
          # deploy to gh-pages branch
          target_branch: gh-pages
          # deploy the default output dir of VuePress
          build_dir: docs/.vuepress/dist
        env:
          # @see https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

:::

::: tip Please refer to GitHub Pages official guide for more details. :::

GitLab Pages

1. Set the correct base config.

   If you are deploying to https://<USERNAME>.gitlab.io/, you can omit base as it defaults to "/".

   If you are deploying to https://<USERNAME>.gitlab.io/<REPO>/, for example your repository is at https://gitlab.com/<USERNAME>/<REPO>, then set base to "/<REPO>/".

2. Create .gitlab-ci.yml to set up GitLab CI workflow.

::: details Click to expand sample config

# choose a docker image to use
image: node:24-buster

pages:
  # trigger deployment on every push to main branch
  only:
    - main

  # cache node_modules
  cache:
    key:
      files:
        - pnpm-lock.yaml
    paths:
      - .pnpm-store

  # Install pnpm
  before_script:
    - curl -fsSL https://get.pnpm.io/install.sh | sh -
    - pnpm config set store-dir .pnpm-store

  # install dependencies and run build script
  script:
    - pnpm i --frozen-lockfile
    - pnpm docs:build --dest public

  artifacts:
    paths:
      - public

:::

::: tip Please refer to GitLab Pages official guide for more details. :::

Google Firebase

1. Make sure you have firebase-tools installed.

2. Create firebase.json and .firebaserc at the root of your project with the following content:

firebase.json:

{
  "hosting": {
    "public": "./docs/.vuepress/dist",
    "ignore": []
  }
}

.firebaserc:

{
  "projects": {
    "default": "<YOUR_FIREBASE_ID>"
  }
}

3. After running pnpm docs:build, deploy using the command firebase deploy.

::: tip Please refer to Firebase CLI official guide for more details. :::

Heroku

1. Install Heroku CLI.

2. Create a Heroku account by signing up.

3. Run heroku login and fill in your Heroku credentials:

heroku login

4. Create a file called static.json in the root of your project with the below content:

static.json:

{
  "root": "./docs/.vuepress/dist"
}

This is the configuration of your site; read more at heroku-buildpack-static.

Kinsta

See Set Up VuePress on Kinsta.

Edgio

See Edgio Documentation > Framework Guides > VuePress.

Netlify

1. On Netlify, set up a new project from GitHub with the following settings:

   • Build Command: pnpm docs:build
   • Publish directory: docs/.vuepress/dist

2. Set Environment variables to choose node version:

   • NODE_VERSION: 24

3. Hit the deploy button.

::: note

You should disable Pretty URLs in the "Site Configuration" → "Build & Deploy" → "Post processing".

:::

Vercel

1. Go to Vercel, set up a new project from GitHub with the following settings:

   • FRAMEWORK PRESET: Other
   • BUILD COMMAND: pnpm docs:build
   • OUTPUT DIRECTORY: docs/.vuepress/dist

2. Hit the deploy button.

CloudRay

See Deploy Your VuePress Site With CloudRay

DeployHQ

DeployHQ is a Git-based deployment platform that builds your VuePress site and transfers the output to your own server over SSH/SFTP/FTP, or to S3, Azure Blob, or Rackspace Cloud Files. It supports build pipelines, atomic releases, one-click rollback, and multiple environments (e.g. staging and production) mapped to different branches of your repository.

1. Sign up for DeployHQ and create a new project, connecting it to your GitHub, GitLab, or Bitbucket repository that contains your VuePress site.

2. Add a build pipeline command so DeployHQ builds your site before transferring it:

   pnpm install --frozen-lockfile && pnpm docs:build

3. Set the build output directory to docs/.vuepress/dist. DeployHQ will only transfer files from this directory to your server.

4. Add a server in your project settings (SSH/SFTP/FTP, S3, Azure Blob, or Rackspace Cloud Files), map it to the branch you want to deploy from (for example main for production), and set the deployment path to your web server's document root.

5. Trigger a deployment manually, or enable automatic deployments so every push to the mapped branch is built and shipped automatically.

::: tip Please refer to the DeployHQ VuePress deployment guide for more details. :::