Setting up a Jekyll Website

5 easy steps to build a modern website hosted by Github

This site is hosted on GitHub Pages. It's mad simple, and I'm pretty satisfied with the workflow so far. This is how I quickly setup a Jekyll project to host on GitHub pages.

Step 1

First install Ruby on your system. A Mac comes pre-installed with a version of Ruby installed by default. With the Terminal.app type sudo gem install jekyll. This will install the Jekyll gem on your computer. The gem allows the commands jekyll serve and jekyll build to be decalred. Check out the Jekyll documentation for specifics, and many more options that this quick setup guide does not cover.

Step 2

Now that the Jekyll gem is installed, use Terminal.app to create a root directory for your Jekyll project by typing sudo mkdir ~/Sites/[project-name] && cd ~/Sites/[project-name] (replacing [project-name] with the name of your project). Now type sudo nano _config.yml to create a configuration file for Jekyll. The config file doesn't need anything specific written to it unless overriding Jekyll's defaults. Here is a basic setup to use when stating a project:

title: "your-site-title"
author: "your-name"
description: "your-site-description"
encoding: UTF-8

Note: Replace "your-site-title", "your-name", and "your-site-description" with the corresponding values. Add as many useful items into the config as possible formatted according to YAML syntax.


Step 3

Jekyll uses a few default directories to build a static site. Each directory is prefixed with an underscore. The most important are _layouts,_includes, and _posts. There is also a _data, but it isn't required. Any other directory without an underscore prefix will be directly copied during the site build. This would be good for something like an assets directory. Jekyll uses what it has called 'Front Matter' to signify to the compiler how to handle individual files. The first file you need to setup is an index.html. Jekyll, much like many other environments looks for this file first to serve the browser. Using the Terminal.app type sudo nano index.html, and then copy the following:

---
layout: default
title: "Home"
slug: index
---
<h1 id="home">Hello World.</h1>
<p>Welcome to {{ site.title }}. A website made by {{ site.author }}.</p>
<p>This is the {{ page.title }} page.</p>

This first tells Jekyll to look for a file in the _layouts directory named defaut.html, and assign this page with a title of "Home", and a slug of "index". You haven't created a defaults.html which will cause Jekyll to fail if you were to run jekyll serve or jekyll build from the Terminal.app, so let's create it now. Using Terminal.app type sudo nano _layouts/default.html and copy the following:

<!DOCTYPE html>
<html lang="en">
{% include head.html %}
  <body class="{% if page.slug != null %}{{ page.slug }}{% endif %}">
  {% include nav.html %}
  {{ content }}
  {% include footer.html %}
  </body>
</html>

Now index.html will resolve to default.hmtl, but you still need to create the includes for Jekyll to successfully build. Using Terminal.app type sudo nano _includes/head.html and use the following code:

<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta name="description" content="{{ site.description }}">
  <meta name="keywords" content="{{ site.keywords }}">
  <meta name="author" content="{{ site.author }}">
  <title>{{ site.author }}</title>
  {% if site.github %}
  <link rel="stylesheet" href="/assets/css/style.min.css">
  {% else %}
  <link rel="stylesheet" href="/assets/css/style.css">
  {% endif %}
</head>


Note: To use the code block above, you must create both a style.css and a style.min.css for the site to run properly. I recommend Gulp or Grunt to lint and minify your CSS.

For the nav.html type sudo nano _inlcudes/nav.html with Terminal.app, and paste the following:

<nav role="menu">
  <ul>
    <li><a href="/index.html#home">Home</a></li>
    <li><a href="/index.html#about">About</a></li>
    <li><a href="/index.html#contact">Contact</a></li>
  </ul>
</nav>

And finally for the footer.html type sudo nano _inlcudes/footer.html with Terminal.app, and paste the following:

<footer>
  <p>&copy; Copyright {{ site.author }}</p>
</footer>
{% if site.github %}
<script src="/assets/js/main.min.js"></script>
{% else %}
<script src="/assets/js/main.js"></script>
{% endif %}

Note: To use the code block above, you must create both a main.js and a main.min.js for the site to run properly. I recommend Gulp or Grunt to lint and minify your CSS.


Use Terminal.app to run jekyll serve form the root directory of the project, and then open your web browser to localhost:4001 to view the site. Jekyll automatically watches you project for changes, and will rebuild the project upon save when using jekyll serve. Alternatively, run jekyll build to only compile compile the project and neither watch nor serve the project.

Step 4

If you do not a have GitHub account, go ahead and sign up. GitHub is a social platform based upon git in which user's code repositories are hosted and shared with the community. Each account also comes with GitHub Pages, a service that will serve static files via Jekyll from a specific repo as a website. Create a repo using the username you signed up with GitHub for the repo title. This signifies to GiHub that you want this repo to also be served. GitHub uses Jekyll to render the static files for hosting.

Using Terminal.app type git init from the root directory. Next type git remote add origin https://git@github.com/username to sync your project and the directory. It is best to copy this command from the GitHub web interface, and be sure to select https from the drop down. Enter your GitHub account password when prompted by Terminal.app. Next Use git commit -am"Initial push" followed by git push -u origin --all to commit and push your project to the new GitHub repo.


Note: You can set up you local machine to use ssh instead of https with GitHub. This allows you to git pull and git push with out being prompted to enter your account password every time. Visit GitHub's Generating SSH keys page for more details.


Step 5

Navigate to http://username.github.io with your browser to view the project website. If you do not see your website right away be patient. Sometimes it takes GitHub Pages a few minutes to build the site from the repo especially on first time builds. GitHub Pages has a nice feature in which if it encounters an error during the build process, it will notify you that it was unsuccessful by email. GitHub Pages also allows you to use custom domain names for your the hosted sites. Do this by purchasing a URL via a Domain Name Service Provider, and then point the record to the GitHub server IP address(es). You can find the current IP with a quick Google Search. GitHub Pages also has good documentation on how to setup custom domains.

Once you can view your site, you can now git commit and then git push your code anytime you wish to add content or update your site, and the changes will appear in realtime. GitHub Pages use Jekyll to build the hosted site, so you can always test changes or features locally first. Remember DRY and try to use Jekyll includes, and layouts. Read the Jekyll documentation for more tips and tricks for more advanced setups and configuration. I suggest first learning Jekyll's built in _data collection. Shopify hosts a Liquid Template wiki on GitHub which is a good starting pointing for Liquid Templates tips and tricks.