# Deploying

The following guides are based on some shared assumptions:

You are placing your docs inside the docs directory of your project;
You are using the default build output location (.vuepress/dist);
VuePress is installed as a local dependency in your project, and you have setup the following npm scripts:

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

# GitHub Pages

Set the correct base in docs/.vuepress/config.js.

If you are deploying to https://<USERNAME>.github.io/, you can omit base as it 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>/".
Inside your project, create deploy.sh with the following content (with highlighted lines uncommented appropriately), and run it to deploy:

#!/usr/bin/env sh

# abort on errors
set -e

# build
npm run docs:build

# navigate into the build output directory
cd docs/.vuepress/dist

# if you are deploying to a custom domain
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# if you are deploying to https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# if you are deploying to https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages

cd -

TIP

You can also run the above script in your CI setup to enable automatic deployment on each push.

TIP

When you use a Custom Domain name, you MUST add the CNAME file into /docs/.vuepress/public folder (Create the folder if it isn’t there). Otherwise, your CNAME file will always be removed with each deploy and never work.

# GitHub Pages and GitHub Actions

Create a personal access token (opens new window);
Create encrypted secrets (opens new window) under your repository;
Create a .yml or .yaml file in the .github/workflows directory in the root of your repository. e.g. vuepress-deploy.yml:

name: Build and Deploy
on: [push]
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@master

    - name: vuepress-deploy
      uses: jenkey2011/vuepress-deploy@master
      env:
        ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
        TARGET_REPO: username/repo
        TARGET_BRANCH: master
        BUILD_SCRIPT: yarn && yarn docs:build
        BUILD_DIR: docs/.vuepress/dist
        CNAME: https://www.xxx.com

For more information, you can checkout jenkey2011/vuepress-deploy (opens new window).

# GitHub Pages and Travis CI

Set the correct base in docs/.vuepress/config.js.

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

If you are deploying to https://<USERNAME or GROUP>.github.io/<REPO>/, for example your repository is at https://github.com/<USERNAME>/<REPO>, then set base to "/<REPO>/".
Create a file named .travis.yml in the root of your project.
Run yarn or npm install locally and commit the generated lockfile (that is yarn.lock or package-lock.json).
Use the GitHub Pages deploy provider template, and follow the Travis CI documentation (opens new window).

language: node_js
node_js:
  - lts/*
install:
  - yarn install # npm ci
script:
  - yarn docs:build # npm run docs:build
deploy:
  provider: pages
  skip_cleanup: true
  local_dir: docs/.vuepress/dist
  github_token: $GITHUB_TOKEN # A token generated on GitHub allowing Travis to push code on you repository. Set in the Travis settings page of your repository, as a secure variable
  keep_history: true
  on:
    branch: master

# GitLab Pages and GitLab CI

Set the correct base in docs/.vuepress/config.js.

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

If you are deploying to https://<USERNAME or GROUP>.gitlab.io/<REPO>/, for example your repository is at https://gitlab.com/<USERNAME>/<REPO>, then set base to "/<REPO>/".
Set dest in .vuepress/config.js to public.
Create a file called .gitlab-ci.yml in the root of your project with the content below. This will build and deploy your site whenever you make changes to your content:

image: node:10.22.0
pages:
  cache:
    paths:
    - node_modules/

  script:
  - yarn install # npm install
  - yarn docs:build # npm run docs:build
  artifacts:
    paths:
    - public
  only:
  - master

# Netlify

On Netlify (opens new window), setup up a new project from GitHub with the following settings:

Build Command: vuepress build docs or yarn docs:build or npm run docs:build
Publish directory: docs/.vuepress/dist

Hit the deploy button.

# Google Firebase

Make sure you have firebase-tools (opens new window) installed.
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>"
 }
}

After running yarn docs:build or npm run docs:build, deploy using the command firebase deploy.

# Surge

First install surge (opens new window), if you haven’t already.
Run yarn docs:build or npm run docs:build.
Deploy to surge by typing surge docs/.vuepress/dist.

You can also deploy to a custom domain (opens new window) by adding surge docs/.vuepress/dist yourdomain.com.

# Heroku

Install Heroku CLI (opens new window).
Create a Heroku account by signing up (opens new window).
Run heroku login and fill in your Heroku credentials:
```
heroku login
```
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 (opens new window).

Set up your Heroku git remote:

# version change
git init
git add .
git commit -m "My site ready for deployment."

# creates a new app with a specified name
heroku apps:create example

# set buildpack for static sites
heroku buildpacks:set https://github.com/heroku/heroku-buildpack-static.git

Deploy your site:

# publish site
git push heroku master

# opens a browser to view the Dashboard version of Heroku CI
heroku open

# Vercel

See Creating and Deploying a VuePress App with Vercel (opens new window).

# Layer0

See Creating and Deploying a VuePress App with Layer0 (opens new window).

← Internationalization Frontmatter →