Written by: Geoffrey Callaghan

how to get started in jekyll

How To Get Started In Jekyll

Getting started with Jekyll, a popular static site generator, involves a few steps. Here’s a detailed guide to help you set up your first Jekyll website:

1. Install Ruby and Jekyll

Jekyll is written in Ruby, so you’ll need to have Ruby installed on your machine. You can then install Jekyll using RubyGems.

Install Ruby

  • For macOS: Ruby comes pre-installed on macOS. To ensure you have the latest version, you can use a version manager like rbenv or RVM.

    brew install rbenv
    rbenv install 3.1.2 # replace with the latest stable version
  • For Windows: Download and install Ruby from the RubyInstaller. Make sure to check the option to install the MSYS2 development toolchain during the setup process.

  • For Linux: Use your package manager to install Ruby. For example, on Ubuntu:

    sudo apt-get install ruby-full

Install Jekyll and Bundler

Once Ruby is installed, you can install Jekyll and Bundler:

gem install jekyll bundler

2. Create a New Jekyll Site

With Jekyll installed, you can create a new site by running:

jekyll new my-blog

This command creates a new directory called my-blog with the default Jekyll site structure.

3. Navigate to Your Site Directory

Move into the new site directory:

cd my-blog

4. Build and Serve Your Site

Jekyll can build your site and serve it locally. To do this, run:

bundle exec jekyll serve

This command builds your site and starts a local development server. Open your web browser and go to http://localhost:4000 to see your site.

5. Customize Your Site

You can customize your Jekyll site by editing the configuration file _config.yml and adding content.

Edit the Configuration File

Open _config.yml in a text editor. Here are some common settings you might want to change:

title: My Awesome Blog
email: your-email@example.com
description: >- # this means to ignore newlines until "baseurl:"
  A blog about awesome things.
baseurl: "" # the subpath of your site, e.g. /blog
url: "http://your-domain.com" # the base hostname & protocol for your site

Add Content

Jekyll uses Markdown files for content. You can add a new post by creating a Markdown file in the _posts directory. For example:

jekyll post "My First Post"

This creates a new file _posts/YYYY-MM-DD-my-first-post.md where you can write your post using Markdown.

Customize Layouts and Themes

Jekyll allows you to customize the look and feel of your site through themes and layouts.

  • Using Themes: You can use a Jekyll theme to style your site. To add a theme, update your _config.yml:

    theme: minima

    Then, run:

    bundle install
  • Customizing Layouts: You can create custom layouts in the _layouts directory. For example, create _layouts/default.html to define a default layout for your pages.

6. Deploy Your Site

When you’re ready to deploy your site, Jekyll generates the static files in the _site directory. You can then upload these files to a web server or use a platform like GitHub Pages.

Deploy to GitHub Pages

  1. Create a GitHub Repository: Create a new repository on GitHub.

  2. Push Your Site to GitHub:

    git init
    git add .
    git commit -m "Initial commit"
    git remote add origin https://github.com/yourusername/your-repo.git
    git push -u origin master
  3. Configure GitHub Pages: In the repository settings, enable GitHub Pages from the master branch or gh-pages branch.


By following these steps, you’ll be able to set up and customize a Jekyll site tailored to your needs. Happy building!