Building a website with Jekyll and Github Pages
I've heard a lot of people talking about GitHub Pages recently, so I decided to find out what the fuss was about. If you've been hiding under rock like me, Github Pages allow you to host a website directly from a Github repository — no separate hosting account necessary. It also integrates with Jekyll — a simple, blog-aware, static site generator — so getting a website up and running couldn't be easier.
Configuring Github Pages
Head over to the GitHub Pages home page for detailed instructions, but essentially it boils down to three simple steps:
- Create a new repository in your Github account named
<username>.github.io. Note: The
<username>part must match your Github username exactly for it to work. Take a look at my Github Pages repository as an example.
- Clone the repository to your own machine using your favorite git client.
- Create an
index.htmlpage and commit back to the master branch.
Once you have followed the above steps you should be able to browse to
yourusername.github.io in a web browser and see your shiny new website. My site is nickrigby.github.io.
You can also verify that everything is working correctly if you open the "settings" tab in your repository in Github. About half way down the page you should see the Github Pages section, where you can administer additional options. You'll notice that one of the options is "custom domain", which I covered in another post.
If you don't already have a site, you should seriously consider installing Jekyll. In their own words "Jekyll is a simple, blog-aware, static site generator perfect for personal, project, or organization sites. Think of it like a file-based CMS, without all the complexity.". Yup, that'll do!
Note: Be sure to check out the Jekyll Requirements Page prior to running these commands, to make sure you have all of the necessary dependencies.
gem install jekyll bundler jekyll new my-awesome-site cd my-awesome-site bundle exec jekyll serve
If everything worked, you should be able to view your site at a localhost address like
http://127.0.0.1:4000/. Note: You'll need to run the
bundle exec jekyll serve every time you want to start the server, or make changes to your
_config.yml file (discussed below).
Configuring Jekyll with Github Pages
In your shiny new Jekyll installation directory you should see a
Gemfile at the root of your project. We need to make a couple edits to this page for the best compatibility with Github Pages. Open the file in your favourite editor and make two changes:
- Line 12(ish), comment out (or remove)
gem "jekyll", "3.2.1"
- Line 19(ish), uncomment
gem "github-pages", group: :jekyll_plugins
Take a look at my Gemfile to see a complete example. Once these edits have been made, run the following:
gem update bundler bundle update bundle install bundle update github-pages
Jekyll and the Github Pages gem should now be ready to go go! Re-run the
bundle exec jekyll serve command, to start the server.
Configuring your development environment
Like any site, you will often require different configuration settings for production vs. development, and Jekyll is no different. Jekyll handles these settings via a simple YAML file found at the root of your project called
_config.yml. We can create additional configuration settings for our development environment by adding a new file called
By creating this file you can override values from the
_config.yml file that are specific to the development environment, so you only need to override values that are different, rather than duplicating the whole file. Take a look at default configuration file and development configuration file for comparison.
Once this file has been created, we need to tell Jekyll to use it. Remember the
bundle exec jekyll serve command from earlier? We need to add some parameters to this command to tell Jekyll about our new development configuration.
bundle exec jekyll serve --config _config.yml,_config-dev.yml
This new command now tells Jekyll to load both configuration files, with the second file overriding values in the first. Neat huh? Also, if you have a terrible memory like me, you might want to save this command as an alias in your bash profile, so it's easy to execute later. I added the following to my
alias jekyll-serve="bundle exec jekyll serve --config _config.yml,_config-dev.yml"
Now you can just run
jekyll-serve from your project folder.
Launch that sucker!
Alright, that's it! Commit all of your changes, sit back and admire your sweet new website. I hope you'll agree that using Github Pages and Jekyll makes it really easy to build a fully functional, hosted website in literal minutes. I hope you found this post useful, and if you have any questions or comments, please let me know below.