Jekyll custom plugins in Github page

Github page, which uses Jekyll as it static site generator, is a very convenient way to host a personal website. However, Github only supports some official plugins they listed, to use other plugins, you have to build the site yourself. In this post, I would like to discuss their difficulties and how to overcome them.

Problems

The first problem is, of course, Github does not support custom plugins and they have a valid point to do so - security. Allowing arbitrary code to run on their server is somewhat vulnerable and they don’t want to do so. Hence, I do not expect them to change that anytime soon. However, some plugins are really helpful, in my case, I need plugins to generate category, month archive and tag archive file automatically instead of the painful official way to generate each of them manually as guided when you add any tag or category.

To overcome this, the only way is to build the website your own and upload the static site to Github. I move all of my site source code to a src/ folder and build the static site to the main directory. However, the second problem comes in when you cannot set the destination folder including the source folder. Because of these tricky things, I have to use a quite complex solution as bellowing.

My solution

Step 1.

To keep the code clean, I don’t want my development code and generated one to be mixed and also I don’t want my commit history to be full of built logs, I create a branch named develop and set it to the default branch, this branch will how the source code. The master branch will hold the static site. So, now I have two branches like this:

branches:
-develop (default branch)
-master (hold static site)

Step 2.

In the develop branch, I add a couple of files, the dirrectory look like this:

-src/  (to hold website jekyll code)
-build_Site.sh (to build the webiste for development)
-clean.sh (clean the built site)
-.gitignore (ignore the built files) 

In .gitignore, I would like to exclude all files generated in the build process:

#ignore temporary files
_site
.sass-cache
src/*.gem
src/*.sublime-project
src/*.sublime-workspace
src/.bundle
src/.DS_Store
src/.jekyll-metadata
src/.sass-cache
src/_asset_bundler_cache
src/_site
src/codekit-config.json
src/Gemfile.lock
src/node_modules
src/npm-debug.log*

In clean.sh, all ignored files is deleted.

#!/bin/sh
git clean -fdX

In build_Site.sh, I build the jekyll site to verify in the development process:

#!/bin/sh
./clean.sh
cd src
bundle exec jekyll build --destination ../_site
cd ../_site
jekyll serve

Note that, the built site is in _site directory so you should run jekyll serve there.

Step 3.

In the master branch, my home directory looks like this:

-src/ (will be updated from develop branch)
- build_Site.sh
- .gitignore (ignore the src folder)
- .nojekyll (avoid jekyll to build this directory)
- _config.yml (if .nojekyll does not work, exclude src folder from being built)
- files generated by Jekyll

my build_Site.sh is as bellowing. Other files are as simple as they are described.

#!/bin/sh
rm -r src
git checkout develop src/
cd src
bundle exec jekyll build --destination ../_site

cd ..
rsync -av --delete --exclude _site/ --exclude src/ --exclude .git/ --exclude .gitignore --exclude .nojekyll --exclude _config.yml --exclude build_Site.sh _site/ ./
rm -r _site

All my code can be viewed in the source code of this website. If you have any better solution to work around with this, please leave me a comment.