Long story short: Jekyll is a template engine changing
documents on static
webpages, that you can then host anywyere, because you don't need databases or server that has PHP or Python.
Normally the process of adding new post looks like this:
The above process works entirely automatically, no need of configuration on repo site or GitHub itself. All you need is having repo name that follows this pattern:
. Normally it works. But...
Sometimes you want to add something cool to your page. I wanted to have it in multiple languages, like Polish and English. Jekyll is not supporting this natively… but it is not impossible 😄
So I’ve found a plugin Polyglot, that allows adding many languages on same page without need of complete rebuild or restructure. I used it, after a while it was kinda working. After a while longer it was working as I wanted. Locally.
After pushing changes to GitHub page wasn’t working properly. I learned that GitHub is not simply building everything you throw at it, but it has a whitelist of supported plugins. Polyglot is sadly not on this list, despite its creator's attempts to get it on the list. Whitelist itself is understandable for security reasons, we don’t want to GitHub go down because of some evil plugin or hidden bitcoin miner running on GitHub servers.
Like every problem this one also has a solution. Even few of them. You can build the page locally and push it to the
branch, and keep source on other branch like
. There is also NodeJS package, that publishes NodeJS apps as GitHub Pages.
But I’m lazy and I don’t want to build manually and push sources and build
result separately, also I don’t have NodeJS app, so I use solution number 3.
GitHub Actions is a basic CI available for free for every repository. To use this CI you need to create Workflow with yaml configuration telling it what and when should happen. There are many available actions, and if something is missing, you can do one yourself or combine few into one workflow. To add workflow go to your
and then click link to set up a workflow yourself.
This will add yaml file with config inside repository in directory
To publish Jekyll blog with not whitelisted plugins I used Jekyll-Actions configured inside workflow like this:
name: 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: $-gems-$ restore-keys: | $-gems- # Standard usage - uses: helaili/[email protected] env: JEKYLL_PAT: $ # Specify the Jekyll source location as a parameter - uses: helaili/[email protected] env: JEKYLL_PAT: $
This action runs inside
container, and then:
, with a push that is possible thanks to
And this publishing on branch master means that you shouldn't push source changes to this branch. If you want to use this action, you need to push changes to develop and leave master only for files build and pushed by the script.
Action itself works in isolated container and has no write access to your
repository. It can read it because its public. To allow this, you need to create access token with public_repo scope, and then add it in repository as a secret with name expected by configuration
You generate token from GitHub account settings:
. After clicking on Generate new token fill the name and select checkbox public_repo.
Settings->Developer Settings->Personal Access Tokens
After clicking button on the bottom Generate token you will have the only chance to copy it, I suggest taking it 😃
Copied token needs to be pasted to repository secrets:
. Name like in config
and value is copied token.
And it should work. At least works for me 😏
This article was also posted on Jekyll blog hosted on GitHub, with the use of free Github Pages.
Previously published at https://asvid.github.io/github-page-deployment