In a previous article, I covered the ins and the outs of the static site generator called Jekyll, and why I have fallen in love with it for simple sites. At its core is Ruby along with the Liquid template engine and Markdown for formatting text. You can do a lot with standard HTML and CSS, but a framework like Bootstrap provides a much better starting point.
This week we look at styling your site with Bootstrap along with the tight integration available in GitHub, where you can host a Jekyll site for free.
GitHub loves Jekyll
There is a tight integration between Jekyll and GitHub, as the latter uses the former as the backbone of its popular GitHub Pages feature. The one caveat with the marriage is Jekyll plug-ins are not supported, as GitHub doesn’t want to open a door for rogue code. When using the two together, you will still want to run Jekyll locally, so you can make changes and preview before sending to GitHub. Thankfully, a Ruby gem is available that sets up everything to make sure you have all of the necessary versions and such. The gem is called github-pages, and it can be installed with the following line:
gem install github-pages
Furthermore, the GitHub documentation recommends running Jekyll with Bundler to mirror the functioning of GitHub’s build server. Using this approach, the following lines are placed in your gemfile:
Once the gemfile is in place, the following command is used to run Jekyll locally:
bundle exec jekyll serve
With everything set up and tested locally, you can send the changes to your GitHub repository. This can be accomplished a number of ways. The method I used for this article was creating an empty repository for my GitHub Pages site (aspatton.github.io) and then pushing the files from my local repository to the empty one on GitHub (my local repository is in a directory named aspatton.github.io):
get remote set-url origin email@example.com:aspatton/aspatton.github.io.git
git push origin master
There are many ways to accomplish this task. You could create everything on GitHub and then use a pull request to pull everything down to a local repository. Regardless of how it is set up, once it is you can push and pull changes to and from GitHub.
Bootstrap joins the party
The basic interface created and presented by Jekyll is nice, but it can be greatly enhanced with one of the many freely available frameworks. I like Bootstrap, so I will use it to enhance my site presentation. The Jekyll-Bootstrap project makes this as easy as setting up Jekyll, so you can have a Bootstrap-themed site up in a relatively short time. It includes all necessary Bootstrap as well as Jekyll components, and there are some themes you can use or create your own.
The first step with taking advantage of the Jekyll-Bootstrap project is cloning its git repository. Once cloned locally, you may run it just like a basic Jekyll installation. The following commands show how this may be accomplished (just substitute your local directory information):
git clone https://github.com/plusjade/jekyll-bootstrap.git [local directory path]
cd [local directory path]
In addition, you may use this site for the basis for your GitHub Pages site. You simply push the Jekyll-Bootstrap code to your GitHub repository as we did previously:
git remote set-url origin firstname.lastname@example.org:USERNAME/USERNAME.github.io.git
git push origin master
This assumes an empty repository, so you may need to pull the site down first and then push changes — there are a number of ways to accomplish it. If you prefer point-and-click instead of the command line, the GitHub GUI interface is a nice solution to working with your repositories.
While Jekyll is simple and straightforward to use, its template engine (Liquid) seems to have a bit of a learning curve. I mention it only because it is what the Jekyll-Bootstrap project uses to fully incorporate Bootstrap into Jekyll’s ecosystem. A quick look at the directory structure after Jekyll-Bootstrap is installed shows a number of new directories and files. For example, there is a directory called _theme_packages as well as a themes directory under the assets directory. Once the site is generated (via Jekyll command), the themes directory is in the assets directory within the _site directory where the generated site file files are stored. You can learn more about directory structure and building custom themes online.
There are a number of themes freely available online. A site can be switched to a new theme with a few commands. It begins with installing the new theme. Once installed, the site is told to use the new theme; this is accomplished with a rake command. I am using Windows, so I open a Git Shell window and enter the following command within my local site directory to install the minimum theme:
Rake theme:install git="https://github.com/jekyllbootstrap/theme-the-minimum.git"
Figure A shows the command issued; notice the final output of the command is a prompt asking if you want to switch the site to the theme now. You can switch themes (the ones installed) via the following rake task:
rake theme:switch name="the-minimum"
Installing a new template for a Jekyll-Bootstrap based site.
Only the beginning
Jekyll offers a great way to generate a static site, and GitHub provides a wonderful (free) vehicle for publishing. Now, add Bootstrap, and your site presentation is greatly enhanced.
It is a great mix of technology, but there is much more available. For example, you can use plugins to add more features to your Jekyll-based site; the only caveat is plugins are not supported on GitHub, but like everything on the web there are workarounds that basically tell you how to build a Jekyll site locally and copy to GitHub (this bypasses GitHub building or compiling it). I like the simplicity of Jekyll with GitHub and Bootstrap integration, along with the ability to go even further when/if the need arises.