Need help with jekyll-action?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

helaili
148 Stars 75 Forks MIT License 225 Commits 2 Opened issues

Description

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

Services available

!
?

Need anything else?

Contributors list

# 123,641
JavaScr...
Vue.js
Shell
HTML
152 commits
# 77,025
HTML
JavaScr...
algolia...
lunr
20 commits
# 241,838
Kotlin
JavaFX
kotlin-...
kotlin-...
7 commits
# 98,613
React
React N...
Swift
Jupyter...
3 commits
# 42,304
HTML
JavaScr...
algolia...
ruby-ge...
1 commit
# 315,912
freerto...
HTML
Shell
JavaScr...
1 commit
# 187,067
JavaScr...
softwar...
Markdow...
k8s
1 commit
# 75,988
HTML
jsf
cdi
JavaScr...
1 commit
# 120,488
Clojure
open-gr...
Clojure...
Markdow...
1 commit
# 84,582
Compose...
php7
raml
cpluspl...
1 commit

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.

Remember that GitHub is serving your built static site, not it's 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
-option. Keep in mind to set the source branch accordingly at the GitHub Pages Settings page.

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 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/[email protected]
action in your workflow file. It needs access to the out-of-the-box
GITHUB_TOKEN
secret. 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. The action will search for Gemfile location. If your want to specify it explicitly (e.g. if you have multiple Gemfiles per project), you should update
gem_src
input parameter accordingly.

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/[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.

image

Just click on the View deployment button of the

github-pages
environment to navigate to your GitHub Pages site.

image

Inputs

token

The

GITHUB_TOKEN
secret. This is mandatory unless
build_only
is set to
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

build_only

When set to

true
, the Jekyll site will be built but not published

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
to install ImageMagick.

keep_history

When set to

true
, previous version of the site will be restored before the Jekyll build takes place. You can then use the
keep_files
option
in your
_config.yml
file to select the files you want to keep. Make sure you then keep at least the
.git
folder. This option will also remove the
--force
flag from the
git commit...
command.
keep_files: [.git, hello.html]

Deprecation

This action previously used a

JEKYLL_PAT
environment variable instead of the
token
parameter. This is now depreacted.

I have a problem

Create a

ACTIONS_STEP_DEBUG
secret with value
true
and run the workflow again.

Note on custom domains

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

CNAME
file exists in the repository root of the
main
(or
master
) branch so that it can be copied to the deployment root when your site is deployed.

If your GitHub Pages site is run off the

main
(or
master
) branch, you can modify the Custom Domain setting in the Repository Settings to automatically generate and commit the
CNAME
file.

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

CNAME
file with your custom domain as its contents, otherwise the file will be committed to the deployment branch and overwritten the next time the action is run.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.