As of the writing of this article, this blog’s content is generated using Jekyll and hosted on GitHub Pages. Until recently all was well: I pushed my code to the
master branch on my website’s repository and GitHub took care of generating the website for me using Jekyll. All this changed when I started needing to use a custom Jekyll plugin, as GitHub Pages don’t support custom plugins due to security concerns.
What is needed in order to use GitHub pages with custom plugins is to generate the website locally and then upload the generated content to a special branch on your repository called
The solution that I’ve implemented involves creating a pre-push git hook that will do the following if it sees a push on the
- build the Jekyll website locally
- moves the
_sitefolder that contains the generated website somewhere outside of the current folder (I choose the parent folder for simplicity)
- checkout the
gh-pagesbranch and remove everything from the working directory
- copy back the content of the
_sitefolder directly into the current working directory
- commit and push the newly copied content on the
What we need to do first is to set-up our repository for this purpose.
First thing that we need to do is make sure we have Jekyll installed locally. Please check Jekyll documentation for that.
Afterwards, we need to make sure we have the
gh-pages branch on the repository. To do this, run the following terminal command in your local repository folder:
git checkout -b gh-pages git push origin gh-pages
If you already have the
gh-pages, just run
git checkout gh-pages.
Next, we’ll need to make sure this new branch doesn’t contain anything. This is especially the case when we don’t do this at the inception of the repository and the
gh-pages will basically inherit the content from the branch we made it from.
To clean the
gh-pages branch, run the following in the terminal:
git checkout gh-pages rm -rf * git add -A git commit -m "Initialized gh-pages branch" git push
Now that the
gh-pages branch contains no file, we’re ready to add the git hook that will take care of generating the content for us.
First let’s create the git hook file:
This will create a file in the
.git/hooks folder called pre-push. Open it in your preferred editor and paste in the following content:
Please note the comments in the above code (lines starting with #) which explain what each section of the code does. You should find steps that are listed in the beginning of this article.
And that’s it! Now, every time you push a commit to the
master branch, you
gh-pages branch should be updated with the content of your website.
Hope this helps! 👍