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
Set the correct base config.
If you are deploying to
https://<USERNAME>.github.io/
, you can omit this step asbase
defaults to"/"
.If you are deploying to
https://<USERNAME>.github.io/<REPO>/
, for example your repository is athttps://github.com/<USERNAME>/<REPO>
, then setbase
to"/<REPO>/"
.Choose your preferred CI tools. Here we take GitHub Actions 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: 20
# 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 }}
Tips
Please refer to GitHub Pages official guide for more details.
GitLab Pages
Set the correct base config.
If you are deploying to
https://<USERNAME>.gitlab.io/
, you can omitbase
as it defaults to"/"
.If you are deploying to
https://<USERNAME>.gitlab.io/<REPO>/
, for example your repository is athttps://gitlab.com/<USERNAME>/<REPO>
, then setbase
to"/<REPO>/"
.Create
.gitlab-ci.yml
to set up GitLab CI 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
Tips
Please refer to GitLab Pages official guide for more details.
Google Firebase
Make sure you have firebase-tools 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
pnpm docs:build
, deploy using the commandfirebase deploy
.
Tips
Please refer to Firebase CLI official guide for more details.
Heroku
Install Heroku CLI.
Create a Heroku account by signing up.
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.
Kinsta
See Set Up VuePress on Kinsta.
Edgio
See Edgio Documentation > Framework Guides > VuePress.
Netlify
On Netlify, set up a new project from GitHub with the following settings:
- Build Command:
pnpm docs:build
- Publish directory:
docs/.vuepress/dist
- Build Command:
Set Environment variables to choose node version:
NODE_VERSION
: 18
Hit the deploy button.
Vercel
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
- FRAMEWORK PRESET:
Hit the deploy button.