gilesvangruisen / jekyll-action

A GitHub Action to publish Jekyll based content as a GitHub Pages site

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.

Note that this is a rather simple (naive maybe) Docker based action. @limjh16 has created a JS based version of this action which saves the container download time and might help with non default use cases.

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 (needs public_repo scope). 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 jekyll_src parameter (sample_site for us). The SRC environment variable is also supported for backward compatibilty but it is deprecated.

Use the actions/cache action in the workflow as well, to shorten build times and decrease load on GitHub's servers

name: Testing the GitHub Pages publication

on:
  push
    
jobs:
  jekyll:
    runs-on: ubuntu-16.04
    steps:
    - uses: actions/checkout@v2

    # Use GitHub Actions' cache to shorten build times and decrease load on servers
    - uses: actions/cache@v1
      with:
        path: vendor/bundle
        key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
        restore-keys: |
          ${{ runner.os }}-gems-

    # Standard usage
    - uses:  helaili/jekyll-action@2.0.1
      env:
        JEKYLL_PAT: ${{ secrets.JEKYLL_PAT }}
    
    # Specify the Jekyll source location as a parameter
    - uses: helaili/jekyll-action@2.0.1
      env:
        JEKYLL_PAT: ${{ secrets.JEKYLL_PAT }}
      with:
        jekyll_src: 'sample_site'

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 as the value of the JEKYLL_PAT env variable, as opposed to a Personal Access Token set as a secret. But it might work too 😄