Using Jekyll and GitHub Pages

Jekyll is a static site generator, meaning there’s no database on the backend.

Jekyll runs from the terminal. For instance, to create a new blog you run

jekyll new blog

And to view your site locally on port 4000 you run

jekyll serve 

This is the directory structure after running jekyll new blog

|   _config.yml
|   index.html
|   feed.xml
|   css
|   _includes
|   _layouts
|   _posts
|   _sass
  • localhost:4000/about
  • _config.yml Global configuration options.
  • index.html localhost:4000/
  • feed.xml RSS feed built by jekyll.
  • css Public folder to store your css files.
  • _includes Reusable parts of your site such as a navbar or footer.
  • _layouts Your content can be structured using different layouts. For instance, your home page would use a different layout than your posts.
  • _posts Blog posts are written in here.
  • _sass Jekyll gives you the option of writting your css in sass.


Now we’ll build a Jekyll blog and host it on Github together. First make sure you have installed Jekyll and Git.

Create a new jekyll project called blog

jekyll new blog

cd into blog and run

jekyll serve

Go to localhost:4000 on your web browser and you’ll see

Jekyll localhost:4000

Some of you may have noticed a new folder named _site was created after running this command.

Jekyll builds your entire site into this folder and runs it on localhost:4000.


This works fine for development but in production you must specify your website’s url and baseurl

Open _config.yml and add them

# This would be the name of your repo 
baseurl: /example
# Full url including your username and repo name

If you want to run your site on localhost, comment both out. But remember to add them before pushing to Github.


Login to your Github account and create a new repo

Github new repo

STOP! Don’t run the commands that Github supplies just yet.

First run git init inside your jekyll blog

git init 

Then create a gh-pages branch (GitHub Pages only run in gh-pages branch)

git checkout -b gh-pages

Add the files and commit them

git add --all

git commit -m "Initial commit"

Now look at the page that GitHub provided after creating the repo

Github quick setup

Run only the first command marked in the red box

Replace the second one: git push -u origin master with

git push origin gh-pages

Direct your browser to

GitHub Page with Jekyll


Remember to comment out url and baseurl in your _config.yml when you’re running on localhost and add them when you push to GitHub.