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 (
.kdupress/dist
); - KduPress is installed as a local dependency in your project, and you have setup the following npm scripts:
{
"scripts": {
"docs:build": "kdupress build docs"
}
}
GitHub Pages
Set the correct
base
indocs/.kdupress/config.js
.If you are deploying to
https://<USERNAME>.github.io/
, you can omitbase
as it 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>/"
.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/.kdupress/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.
GitHub Pages and Travis CI
Set the correct
base
indocs/.kdupress/config.js
.If you are deploying to
https://<USERNAME or GROUP>.github.io/
, you can omitbase
as it defaults to"/"
.If you are deploying to
https://<USERNAME or GROUP>.github.io/<REPO>/
, for example your repository is athttps://github.com/<USERNAME>/<REPO>
, then setbase
to"/<REPO>/"
.Create a file named
.travis.yml
in the root of your project.Run
yarn
ornpm install
locally and commit the generated lockfile (that isyarn.lock
orpackage-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/.kdupress/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
indocs/.kdupress/config.js
.If you are deploying to
https://<USERNAME or GROUP>.gitlab.io/
, you can omitbase
as it defaults to"/"
.If you are deploying to
https://<USERNAME or GROUP>.gitlab.io/<REPO>/
, for example your repository is athttps://gitlab.com/<USERNAME>/<REPO>
, then setbase
to"/<REPO>/"
.Set
dest
in.kdupress/config.js
topublic
.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:
kdupress build docs
oryarn docs:build
ornpm run docs:build
- Publish directory:
docs/.kdupress/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/.kdupress/dist",
"ignore": []
}
}
.firebaserc
:
{
"projects": {
"default": "<YOUR_FIREBASE_ID>"
}
}
- After running
yarn docs:build
ornpm run docs:build
, deploy using the commandfirebase deploy
.
Surge
First install surge (opens new window), if you haven’t already.
Run
yarn docs:build
ornpm run docs:build
.Deploy to surge by typing
surge docs/.kdupress/dist
.
You can also deploy to a custom domain (opens new window) by adding surge docs/.kdupress/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/.kdupress/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