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.
Before you get started
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.
Things you should know
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.
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).
Install Jekyll and its dependencies
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.
Set up your new blog with Jekyll
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:
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.
Customize your blog
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.
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.
Deploy your blog to GitHub
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.
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.
Next steps
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.
Kris Wouk is a writer, musician, and whatever it’s called when someone makes videos for the web.
Our latest tutorials delivered straight to your inbox
