How to Create a Blog Using Jekyll

Sat, Nov 10, 2018
3-minute read

One of the most popular tools for creating documentation sites is Jekyll. This post explains how to get started with Jekyll for creating a blog or a documentation site.

Install Ruby

To start with Jekyll you need Ruby 2.4.0 or above. You can check if you have it already installed by running this in your terminal: ruby -v. Ruby is included on macOS, but you can install the latest version with: brew install ruby.

Install Jekyll

Run the following command to install Jekyll along with the bundler gems locally:

gem install --user-install bundler jekyll

Verify you are running this command in your main user directory. The global installation is not recommended.

Create a New Site

Now that you have Ruby and Jekyll you can start creating your blog by following the next steps:

Navigate to a directory where you want to create your site and run:
```
jekyll new yourblogname
```
Navigate to the created directory:
```
cd yourblogname
```
To build the site and make it available on a local server, run:
```
bundle exec jekyll serve
```

Your site is now available at: http://localhost:4000.

Personalize

Basic Information

Jekyll controls the configuration options of your site with the _config.yml file. To customize the basic information about your site, open the _config.yml file and modify the values of:

title
email
description

You can also add your twitter_username and github_username.

About Page

To change the information in the About page, open the about.md file and edit it with your site description or information about yourself. Jekyll uses Markdown so you can use it to edit your posts and pages.

Create Your First Post

Your posts are located in the _posts directory. Move to that directory and follow the next steps:

Create a new file with the following naming pattern: YYYY-MM-DD-yourposttitle.
NOTE: It is important to follow the naming pattern because otherwise Jekyll won’t generate the post.

Add the Front Matter at the top of the file:

---
layout: post
title:  "Your Post Title"
date:   2018-11-10
---

You can start writing your post right below the Front Matter. Use Markdown to write your posts.
Save your file and run bundle exec jekyll serve to see your new post in your site.

Done! You have built your own blog with Jekyll and have created your first post!

Publish Your Blog on Github Pages

You can publish your blog on GitHub Pages, which is already integrated with Jekyll, so you only have to push your changes to your repository and GitHub pages automatically builds the site to go live.

If you haven’t already, initialize a new git repo in your project’s directory with:
```
git init
```
Save all changes to your new repo with:
```
git add .
```
Commit your changes to the repo:
```
git commit -m "first commit"
```
Go to GitHub.com and create a new repository with the same name of your project.
Once you created your repo on GitHub, click the Clone or download button and copy the HTTPS URL.

Connect your GitHub repository with your local repository:

git remote add origin <paste here the HTTPS URL you copied from GitHub>

Push your changes:
```
git push origin master
```
Go back to your Github.com repository and navigate to Settings.
Scroll down to the GitHub Pages section and select master branch as the Source for GitHub Pages.
Save your changes.

You’re done! You can see your site’s URL in the upper part of the GitHub Pages section.

static site generators github jekyll