How to Host Your Blog for Free with Jekyll and GitHub Pages

If you’re looking to start a blog, chances are the first name you’ll encounter is WordPress. There’s a reason for that. WordPress is incredibly flexible and powers huge websites as well as small ones. The thing is, not every website needs such a powerful infrastructure, especially a simple blog.

Smaller, simpler, and cheaper options are available. GitHub Pages, for example, is free for personal use. Combine that with Jekyll, a static site generator, and you have everything you need for a blog. Even better, it’s free.

You’ll be running Jekyll on your own computer, and only macOS and Linux are officially supported. We’ll be covering both operating systems here, and the Linux instructions may work with the Windows Subsystem for Linux running Ubuntu. That said, it hasn’t been tested.

You’ll also want access to a good text editor. TextEdit or GEdit will do, but you might want something more robust. We’ve taken a look at several great cross-platform text editors in the past.

You should have at least a passing familiarity with the command line. Being familiar with git and GitHub will be necessary as well. If you’re not familiar, we’ve got a guide to git, and GitHub’s own documentation is excellent.

github-pages-jekyll-launch

Finally, Jekyll utilizes Markdown, which lets you write in plain text but present your content in HTML to the user. You should be familiar with Markdown, or at least willing to learn it. This may sound daunting, but Markdown is easy to learn (we even have a cheatsheet for it).

This has been tested on macOS Mojave and Ubuntu 18.04. If you’re running another version of either operating system, you may need to check the Jekyll website for further information.

macOS

Before you can install Jekyll, you need to install the XCode command line tools with the following command:

Select Install and wait for the installer to complete. Now you can install Jekyll and Bundler:

When you run this command, you’ll see a warning similar to the one below:

WARNING: You don't have /Users/YOURNAME/.gem/ruby/2.3.0/bin in your PATH, gem executables will not run.

Note the version number. Assuming the above message, run the following commands, substituting the correct version number if it differs:

Ubuntu

Before installing Jekyll, you’ll need to install the build tools with the following command:

As with macOS, we want to install and run from the home directory instead of as root. Run the following commands:

Now install Jekyll and Bundler:

Test your Jekyll installation

To make sure everything is up and running, run the following:

If everything has installed correctly, you’ll see a message with the version number. If instead you see a message like command not found, see the Jekyll documentation.

Now that Jekyll is installed, creating your new blog is simple:

You can use any name you want in the above command instead of blog. This is simply the name of the directory Jekyll creates. Now cd to the directory that you just created, and run the following command:

github-pages-jekyll-blog-in-browser

This will launch your new blog about running locally on your computer. Open the URL displayed in your browser to take a look at the site. As you can see, there’s some work to do. Press Ctrl + C to stop.

To edit the site title and other information, open your blog directory and edit “_config.yml”. The various options here are fairly obvious. Now if you want, you can edit your home page, which is the “index.md” file, though this is optional.

github-pages-jekyll-config

To get started writing your first blog post, open the “_posts” folder and you’ll see a sample post. Open this up and edit it, or duplicate it to create a new post.

Now that your site is set up locally, it’s time to take it online. If you don’t have a GitHub account set up already, sign up and get git installed and configured on your computer. Next, create a new repository with the name username.github.io, replacing “username” with your GitHub username.

github-pages-jekyll-repo-setup

Now open your terminal and cd to your blog folder. Run the following commands.

Now you should be able to visit username.github.io and see your new blog. If it doesn’t show up right away, wait a few minutes and try again.

The steps above are just the basics to get you up and running. Jekyll has plenty to offer, so be sure to check out the documentation. There are also a number of themes available to spice up the look of your blog.

There are further steps to take with GitHub Pages too. Enabling HTTPS support used to be a more complex process, but now can be done in your repository settings. Setting up your own domain name is a simple process as well, and GitHub has a great guide on how to do so.

One final thing to keep in mind is that it’s a good idea to check site changes locally before committing them to your repository. Simply run the bundler command we used earlier to look at your site on your computer. This will help you catch everything from typos to Markdown syntax errors.

Leave a Comment

Yeah! You've decided to leave a comment. That's fantastic! Check out our comment policy here. Let's have a personal and meaningful conversation.

Sponsored Stories