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 pnpmopen in new window 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 Actionsopen in new window as an example.

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

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@v4
        with:
          # fetch all commits to get last updated time or other git log info
          fetch-depth: 0

      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with:
          # choose pnpm version to use
          version: 8
          # install deps with pnpm
          run_install: true

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

      # 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 guideopen in new window 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 CIopen in new window workflow.

Click to expand sample config
# choose a docker image to use
image: node:18-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 guideopen in new window for more details.

Google Firebase

  1. Make sure you have firebase-toolsopen in new window 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>"
  }
}
  1. After running pnpm docs:build, deploy using the command firebase deploy.

TIP

Please refer to Firebase CLI official guideopen in new window for more details.

Heroku

  1. Install Heroku CLIopen in new window.

  2. Create a Heroku account by signing upopen in new window.

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

heroku login
  1. 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-staticopen in new window.

Kinsta

See Set Up VuePress on Kinstaopen in new window.

Edgio

See Edgio Documentation > Framework Guides > VuePressopen in new window.

Netlify

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

    • Build Command: pnpm docs:build
    • Publish directory: docs/.vuepress/dist
  2. Set Environment variablesopen in new window to choose node version:

    • NODE_VERSION: 18
  3. Hit the deploy button.

Vercel

  1. Go to Vercelopen in new window, 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.