VuePress is most commonly used to build documentation sites.
GitHub Pages is most commonly used to host documentation sites.
# They should just work together, right?
The first thing to realise is that GitHub won't build your site for you. In fact, if you just set GitHub Pages to use your docs folder, it will build you a Jekyll site 😕
If you want your VuePress site on GitHub Pages, you first have to build it yourself and then deploy the content of the .vuepress/dist folder.
The second thing is that there is no way to tell GitHub to deploy the content of your dist folder. That's probably a good thing as it's best practice to
.gitignore compiled files in your codebase. So where do you deploy to?
# The magic
gh-pages branch ✨
The solution to this is to deploy to a branch called gh-pages. This is a special branch name that GitHub recognises and deploys automatically.
The VuePress docs include instructions on how to add a deploy.sh file to your repo, which is especially useful if you want to set up automatic deployment as part of a CI process.
However, if you're looking for the easiest way to start deploying to GitHub Pages, you can do it with one command:
npm run build && npx gh-pages docs/.vuepress/dist
That's all there is to it! 😄
After you run this command, you will find a link to your deployed site in your GitHub repository settings, which will look something like this:
# A little config
Because your site is not hosted at the root of this subdomain, you'll need to add the following inside your .vuepress/config.js file to make sure your links work:
So you don't have to remember the command, add this to your scripts in your package.json file...
"deploy": "npm run build && npx gh-pages docs/.vuepress/dist"
... and then run
npm run deploy.
If you're wondering what the
npx is about, that's a way to use an npm package without having to install it as a dependency. If you prefer, you can run
npm install -D gh-pages and then remove
npx from the above script.
# Demo time :clock:
Here's a working example: