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 instance) used to require a continuous integration build in order to pre-process the site.

Remember that GitHub is serving your built static site, not its sources. So when configuring GitHub Pages in your project settings, use gh-pages branch as a Source for GitHub Pages. If you are setting up username.github.io repository, you'll have to use master branch, so sources can be located in another orphaned branch in the repo (which you can safely mark as default after the first publication). In addition to that default behaviour, you can configure the branch this plugin pushes into with the

target_branch

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 (such as but not limited to: specific package or library that is not available as a Gem).

Usage

Create a Jekyll site

If your repo doesn't already have one, create a new Jekyll site:

jekyll new sample-site

sample_site

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

asciidoc: {}
asciidoctor:
  base_dir: :docdir
  safe: unsafe
  attributes:
    - idseparator=_
    - source-highlighter=coderay
    - icons=font

Note that we also renamed

index.html

index.adoc

Use the action

Use the

helaili/[email protected]

GITHUB_TOKEN

_config.yml

jekyll_src

sample_site

SRC

gem_src

Use the

actions/cache

name: Testing the GitHub Pages publication

on:
  push
jobs:
  jekyll:
    runs-on: ubuntu-16.04
    steps:
    - uses: actions/[email protected]
# Use GitHub Actions' cache to shorten build times and decrease load on servers
- uses: actions/[email protected]
  with:
    path: vendor/bundle
    key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile') }}
    restore-keys: |
      ${{ runner.os }}-gems-

# Standard usage
- uses:  helaili/[email protected]
  with:
    token: ${{ secrets.GITHUB_TOKEN }}

# Specify the Jekyll source location as a parameter
- uses: helaili/[email protected]
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    jekyll_src: 'sample_site'

# Specify the target branch (optional)
- uses: helaili/[email protected]
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    target_branch: 'gh-pages'

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

Inputs

token

The

GITHUB_TOKEN

build_only

true

jekyll_env

The Jekyll environment to build (default to

production

jekyll_src

The Jekyll website source directory

jekyllbuildoptions

Additional Jekyll build arguments (see the Jekyll doc)

gem_src

The Jekyll Gemfile directory

target_branch

The target branch name the sources get pushed to

target_path:

The relative path where the site gets pushed to

build_only

When set to

true

prebuildcommands

Commands to run prior to build and deploy. Useful for ensuring build dependencies are up to date or installing new dependencies. For example, use

apk --update add imagemagick

keep_history

When set to

true

keep_files

_config.yml

.git

--force

git commit...

keep_files: [.git, hello.html]

Use case: multi version publishing

Say you want to create a documentation website where you both have the current version (

v3.0

v1.0

v2.0

keep_history

target_path

actions/[email protected]

... 
  publish-current-version: 
    runs-on: ubuntu-latest
    steps:
    - uses: actions/[email protected]
      with:
        ref: main
    - name: Run with dest path
      uses: helaili/[email protected]
      with:
        target_branch: gh-pages
        target_path: /
        keep_history: true
        token: ${{ secrets.GITHUB_TOKEN }}

  publish-v2-version: 
    runs-on: ubuntu-latest
    steps:
    - uses: actions/[email protected]
      with:
        ref: v2.0
    - name: Run with dest path
      uses: helaili/[email protected]
      with:
        target_branch: gh-pages
        target_path: v2.0
        keep_history: true
        token: ${{ secrets.GITHUB_TOKEN }}
  publish-v1-version: 
    runs-on: ubuntu-latest
    steps:
    - uses: actions/[email protected]
      with:
        ref: v1.0
    - name: Run with dest path
      uses: helaili/[email protected]
      with:
        target_branch: gh-pages
        target_path: v1.0
        keep_history: true
        token: ${{ secrets.GITHUB_TOKEN }}

Deprecation

This action previously used a

JEKYLL_PAT

token

I have a problem

Create a

ACTIONS_STEP_DEBUG

true

Note on custom domains

If you're using a Custom Domain for your GitHub Pages site, you will need to ensure that the

CNAME

main

master

If your GitHub Pages site is run off the

main

master

CNAME

If your GitHub Pages site is run off an alternate branch, however, you will need to manually create and commit the

CNAME