Learn to create your own (dev)-blog using Jekyll!

Setting up Jekyll locally

Staring off with Jekyll is extremely easy! First of all, we’ll start by setting up our simple environment:

1. Setting up a Ruby environment

You may ask

“Why do I even need Ruby installed?”

Well, Jekyll is a Ruby Gem (think of a gem as a packaged code/software to be reused by others), and therefore requires you have Ruby installed on your machine. For Jekyll, we need Ruby version 2.2.5 or above, so keep that in mind when you install it if you have to pick a version.
Let’s get started:


  • To get set up on windows, you will need to download Ruby+Devkit from RubyInstaller site
    (I downloaded 2.5.3 at the time of this tutorial, but anything 2.3 and above should be good!)


  • Ruby actually came preinstalled on my Mac. If you are having issues with it though, visit the Jekyll Official instructions for more details on how to install it using HomeBrew or other methods.

2. Installing Jekyll

Once you have your Ruby environment set up, it’s time to install Jekyll.

Run the following command in your CLI of choice:

$ gem install bundler jekyll

(make sure to launch a new instance of your CLI so that your path variables would update)

  • Note, I had to also run bundle install on my Windows machine due to various missing gems.

Verify Jekyll has been installed by running jekyll -v

3. Creating Your Blog Locally

this is pretty straight forward, just run this simple command!

$ jekyll new MY_BLOG_NAME

Replace MY_BLOG_NAME with your blog name. Jekyll will now create a new project in your current working directory inside of a new folder named after your blog!

4. Running a Jekyll Server Locally

We are pretty much done setting up our Jekyll environment! Check our your blog by running the server! Run the following command to start up the server:

$ jekyll serve

If that didn’t work, check if there are any gems you need to install by running bundle install and then try to launch it explicitly using bundle as follows: bundle exec jekyll serve

Now open your web browser of choice and navigate to localhost:4000 OR and you should be able to see your site!

Understanding the Jekyll Environment

Jekyll Folders & Files

Your folder hierarchy should look similar to this:

  |- _drafts/     -> Contains posts that should not be published yet
  |- _posts/      -> Contains all of your published posts   
  |- _config.yml  -> Holds site configuration and variables
  |- 404.html     -> Your 404 page for pages that do not exist
  |- about.md     -> Your about page, written in markdown
  |- Gemfile      -> Your dependency management file 
  |- index.md     -> Your homepage

You might not have a _drafts/ folder, so feel free to create one!

The _config.yml File

_config.yml is the file that will hold a lot of valuable information about your site. Jekyll themes will use those variables to configure a lot of the site for you!

I recommend starting off by modifying that file and filling in your blog information such as


Now go back to your site and refresh. You should see various parts of the site updated to use your newly added variables!

.md / .html Files on Root

Markdown files and HTML files on root (index.md, about.md and 404.html) are your regular, non-post, pages.

Feel free to customize your About and 404 pages. Leave index.md as is for now since it is generated by your Jekyll theme and gets populated automatically with your most recent posts!

You can add more .md and .html files to your root, and they will be accessible for you to navigate to. For example, if you add a new test.md (or test.html) file on root, you will then be able to access it by navigating to localhost:4000/test


That’s pretty much it for setting up Jekyll locally! Next up is setting up our GitHub Pages free hosting and connecting it to our custom domain.

My next article will explain how to do so, step-by-step: