A GitHub Action to build and publish Jekyll sites to GitHub Pages
Out-of-the-box Jekyll with GitHub Pages allows you to leverage a limited, white-listed, set of gems. Complex sites requiring custom ones or non white-listed ones (AsciiDoc for intstance) used to require a continuous integration build in order to pre-process the site.
If you repo doesn't already have one, create a new Jekyll site: jekyll new sample-site
. See the Jekyll website for more information. In this repo, we have created a site within a sample_site
folder within the repository because the repository's main goal is not to be a website. If it was the case, we would have created the site at the root of the repository.
As you are using this action to leverage specific Gems, well, you need to declare them! In the sample below we are using the Jekyll AsciiDoc plugin
source 'https://rubygems.org'
gem 'jekyll', '~> 3.8.5'
gem 'coderay', '~> 1.1.0'
group :jekyll_plugins do
gem 'jekyll-asciidoc', '~> 2.1.1'
end
Edit the configuration file of your Jekyll site (_config.yml
) to leverage these plugins. In our sample, we want to leverage AsciiDoc so we added the following section:
asciidoc: {}
asciidoctor:
base_dir: :docdir
safe: unsafe
attributes:
- idseparator=_
- source-highlighter=coderay
- icons=font
Note that we also renamed index.html
to index.adoc
and modified this file accordingly in order to leverage AsciiDoc.
Use the helaili/jekyll-action@master
action in your workflow file. It needs access to the GITHUB_TOKEN
secret (just check the box). The directory where the Jekyll site lives will be detected (based on the location of _config.yml
) but you can also explicitly set this directory by setting the SRC
environment variable (sample_site
for us).
Note that it might be a good idea to use the actions/bin/filter
action so the site is built only when a push happens on master
.
workflow "Jekyll build now" {
resolves = [
"Jekyll Action",
]
on = "push"
}
action "Jekyll Action" {
uses = "helaili/jekyll-action@master"
needs = "Filters for GitHub Actions"
env = {
SRC = "sample_site"
}
secrets = ["GITHUB_TOKEN"]
}
action "Filters for GitHub Actions" {
uses = "actions/bin/filter@b2bea0749eed6beb495a8fa194c071847af60ea1"
args = "branch master"
}
Upon successful execution, the GitHub Pages publishing will happen automatically and will be listed on the environment tab of your repository.
Just click on the View deployment button of the github-pages
environment to navigate to your GitHub Pages site.
Publishing of the GitHub pages site fails when the repository is private. I am investigating this.