Step by Step Tutorial
Welcome to Jekyll’s step-by-step tutorial. This tutorial takes you from having some front-end web development experience to building your first Jekyll site from scratch without relying on the default gem-based theme.
Jekyll is a Ruby gem. First, install Ruby on your machine. Go to Installation and follow the instructions for your operating system.
With Ruby installed, install Jekyll from the terminal:
gem install jekyll bundler
Create a new
Gemfile to list your project’s dependencies:
Gemfile in a text editor and add jekyll as a dependency:
bundle to install jekyll for your project.
You can now prefix all jekyll commands listed in this tutorial with
to make sure you use the jekyll version defined in your
Create a site
It’s time to create a site! Create a new directory for your site and name it whatever you want. Through the rest of this tutorial we’ll refer to this directory as root.
You can also initialize a Git repository here.
One of the great things about Jekyll is there’s no database. All content and site structure are files that a Git repository can version. Using a repository is optional but is recommended. You can learn more about using Git by reading the Git Handbook.
Let’s add your first file. Create
index.html in root with the following
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Home</title> </head> <body> <h1>Hello World!</h1> </body> </html>
Since Jekyll is a static site generator, it has to build the site before we can view it. Run either of the following commands to build your site:
jekyll build- Builds the site and outputs a static site to a directory called
jekyll serve- Does
jekyll buildand runs it on a local web server at
http://localhost:4000, rebuilding the site any time you make a change.
When you’re developing a site, use
jekyll serve. To force the browser to refresh with every change, use
jekyll serve --livereload.
If there’s a conflict or you’d like Jekyll to serve your development site at a different URL, use the
as described in the serve command options.
The version of the site that
jekyll serve builds in
_site is not suited for deployment. Links and asset URLs in sites created
jekyll serve will use
https://localhost:4000 or the value set with command-line configuration, instead of the values set
in your site’s configuration file. To learn about how to build your site when it’s
ready for deployment, read the Deployment section of this tutorial.
jekyll serve and go to
your browser. You should see “Hello World!”.
At this point, you might be thinking, “So what?”. The only thing that happened was that Jekyll copied an HTML file from one place to another.
Patience, young grasshopper, there’s still much to learn!
Next. you’ll learn about Liquid and templating.