How to setup GitHub Pages + Actions for use with Jekyll 4
A live demo and introduction around deploying Jekyll 4 to GitHub Pages - using GitHub Actions and the Jekyll Actions action.
Follow one of the approaches below to learn how it works and set up your own site and workflow.
This project was developed as part of writing a step-by-step guide for the Jekyll site's documentation.
Here is the link:
See this project's live demo hosted on Github Pages:
Create your own repo like this one using the button below. Then continue following the setup and run instructions on this page.
How to deploy this project using GH Actions and GH Pages
The part which makes this project run on GitHub Actions is the workflow file - see jekyll.yml. You do not need to modify that file. But, you do need to set a GH API token for it to use. See below.
How to setup as a GitHub Pages site:
- Add this repo to your GitHub repos using the template or fork button. You only need
master
branch. Thegh-pages
branch will get built from scratch later. - Follow the instructions in the tutorial page's Add token section to add
JEKYLL_PAT
to the environment as Secret, so you have a Github Auth token created and added to your repo. - Save a file or push a commit.
- Go to the Actions tab of your repo to see the workflow running.
- On success, it will generate the site, commit to
gh-pages
branch and make the content available GH Pages. - On the very first run, you'll see a success but not actually have the site live. So then you need to go into the Settings of your repo and turn GitHub Pages off and then on again (for
gh-pages
branch). This has been my experience.
- On success, it will generate the site, commit to
- Check the environment section to see the status and the GH Pages URL.
Your GH Pages site is live on GH Pages and now rebuilds and deploys on a commit or push - using custom gems.
Note: The standard GitHub Pages flow actually still run behind the scenes in addition to the GH Actions build (which actually can't serve anything alone). The GitHub Pages service just sees gh-pages
branch as static HTML assets with no Jekyll config, so it will serve the content without processing it through Jekyll.
- Install Ruby.
- Install Bundler as a user gem.
$ gem install bundler --user-level
- Clone the repo or your repo copied from the template.
- Install project dependencies using Bundler. This will include Jekyll 4.
If you like
$ bundle config set --local path vendor/bundle $ bundle install
make
on Linux or macOS, then simply run this instead:$ make install
Start a development server using the project-scoped Jekyll (ignoring any globally-installed Jekyll gem).
$ bundle exec jekyll serve --source sample_site --destination build/ --livereload --trace
Or, using make
:
$ make serve
For this simple demo project with few dependencies, leaving out the Gemfile.lock
file altogether is reasonable.
Note that Gemfile.lock
must remain as file ignored by git
to avoid build errors. This because an install locally with bundle
will put bundler
as a line in Gemfile.lock
, while bundler
use will cause an error on the remote build as its not available (at least in the container used by the chosen Github Action here.
Alternatively, keep the file either build will a global (user-level) Jekyll. Or keep building a Gemfile.lock
remember to manually remove the bundler
reference.
The Makefile
, LICENSE
and README.md
files do not have to be excluded, as this site is setup to build from a subdirectory. Otherwise they would have to be added to the ignore list.
The Gemfile
and Gemfile.lock
are always ignored by Jekyll 4.
- Released under MIT.
- Feel free to modify and reuse this project. You are required to include the license when using this code. Copy
LICENSE
toLICENSE-source
and then modifyLICENSE
with your own name. - Please link back to this repo as well.