Prior to this post, Eumir introduced the Aelogica’s Style Guide. We want to share those pages to the whole dev community so we want to make those pages public. To do that we used gh-pages and jekyll. We decided on those two because they’re free (no hosting fees needed), require minimal setup, and the deployment is fairly easy once you get the hang of it.
A lot of blog posts and tutorials about gh-pages and jekyll have been published but I won’t be making another one from this post. I am also new to the concept and what I would like to share are some of the things that I learned while pair programming our style guide project.
There are two types of Github pages: User/Organization and Project, their main difference is the branch where the html pages are pushed. Our style guide is pushed on the ‘gh-pages’ branch because we want to create a Github Project Page. The pages can be created with a simple html or with Jekyll. We opted to use the latter because it gives us freedom to use markup languages other than html.
Jekyll can parse liquid codes called from the main layout template. Liquid Templating is very useful for rendering dynamic contents. It can also be extended to allow custom methods. Examples of custom methods are ‘include_css’ and ‘include_js’ that we’re using on this project. We created the method because we want to get the correct asset path based on the current instance environment. Our custom methods are defined in AssetTag class which extends the Liquid::Tag. We placed them all on a file inside the ‘_plugins’ folder.
Once all the pages are done, everything is in the right place, all files have the proper file names (note that files with names starting with underscore will not be parsed), we’re ready to deploy to production. Our deployment is a multiple step process and we put them all in a rake task executing the following:
- Pre-compile haml files (our main layout is in haml)
- Run ‘jekyll’ command to parse all posts, pages and template files and store them all on ‘_site’ folder
- Copy ‘_site’ folder to a temporary folder
- Switch to ‘gh-pages’ branch
- Replace all contents of root with the contents of ‘_site’ folder
- Create a ‘.nojekyll’ file to stop Github from re-parsing the contents of ‘gh-pages’ branch
- Git add & commit all files
- Remove the temporary folder holding the contents of ‘_site’ folder
We conclude the process by pushing all files to ‘gh-pages’ branch.