Cover image by the magnificent Andre Wallin

One of the caveats of GitHub Pages is that it won’t automatically build your site if you’re not using the GitHub Pages Jekyll gem. On top of this, you can’t use any Jekyll plugins that aren’t supported by GitHub Pages.

That being said, GitHub will deploy compiled code for you, either from the /docs folder, a gh-pages branch or from the master branch. [ref]

The solution I’m using right now means still I’m able to run my build process locally and auto-deploy with a single command.

So for this to work, I’ve set up two branches for my site:

• master contains my Jekyll compiled _site/ folder, which GitHub will deploy each time it’s pushed.
  • .nojekyll should be added to this branch so GitHub doesn’t attempt to compile it.
• sources contains the full repo, with the Jekyll source files.
  • This method could work with any static site generator.
  • _site/ should be added to the .gitignore on this branch, so you don’t commit the changes in there.

I’ve written a simple npm shell script that runs with npm deploy, which is essentially an alias for the following string of commands:

bundle exec jekyll build &&
cd _site/ &&
git add . &&
timestamp=$(date \"+%s\") &&
git commit -m \"automated deployment $timestamp\" &&
git push origin master &&
cd ..

Each time I want to deploy:

1. The jekyll build command compiles and builds my static site inside the _site/ folder.
2. We then change directories to _site/, which has a .git config, set to the master branch of the repo.
3. The script then commits all changes (+ timestamp), pushes master and returns to my source folder.

That’s it! So now, once I’ve made changes to my site or content, I can still have my site built and deployed with a single command.

Further reading

Moving from Ghost CMS to Jekyll
GitHub Pages Basics
Official Jekyll Docs