jekyll-action

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.

Usage

Create a Jekyll 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.

Create a Gemfile

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

Configure your Jekyll site

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 action

Use the helaili/jekyll-action@master action in your workflow file. It needs access to a JEKYLL_PAT secret set with a Personal Access Token. 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 = ["JEKYLL_PAT"]
}

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.

Known Limitation

Publishing of the GitHub pages can fail when using the GITHUB_TOKEN secret instead of the JEKYLL_PAT. But it might work too :smile: