Image: Creating a blog-portfolio using Jekyll & GitHub Pages by Jennie Ron Ablog

Welcome! I just made this website with Jekyll, an open source static page generator, and I’m hosting it using GitHub Pages. All the services I used are 100% free. I’m currently using this grape-theme with only a few modifications to the original code. You can find my source code here.

This serves as a guide on launching your github website using Jekyll and Github Pages.

Prerequisites

Skills

  • Basic HTML and CSS
  • Git

Installations

  • Ruby (programming language)
  • Git (version control)
  • GitHub (you need an account)
  • Bundler
  • Here is a complete installation guide from the Jekyll website.


Outline

  1. Get started with Github.
  2. Find a theme for your Jekyll site.
  3. Personalize your Jekyll site.
  4. Deploy your site to GitHub pages.
  5. Write your first blog post.


1. Get started with GitHub.

  1. Sign in to your GitHub account.
  2. Create a new repository and name it [username].github.io, replacing [username] with your GitHub username. Be sure the first part of the repo name exactly matches your username and that you set your repository to public. Otherwise, it will not work.
  3. Create a .gitignore file and add the following line: _site/. This file tells git to ignore the _site directory that Jekyll automatically generates each time a commit is made.
  4. Open your terminal and create a local copy of your website on your computer using the command below. 
    git clone https://github.com/[username]/[username].github.io.git

    This way you can always preview your Jekyll site first before pushing it to GitHub pages.


2. Find a theme for your Jekyll site.

  1. You can find, preview, and download themes for your Jekyll site on different galleries found online such as the following:
  2. Once you’ve chosen a theme, download and extract the file to your local git repository at ~../[username].github.io/.

    You can always choose to write your own HTML and CSS independently. I just find it much more convenient and time-efficient to pick a pre-made theme and personalize it to my liking.

  3. On you local git repository, install dependencies for your Jekyll site. 
    bundle install
  4. Finally, run the server to test your site locally. 
    bundle exec jekyll serve

    It should be up and running at http://localhost:4000/.


3. Personalize your Jekyll site.

  1. Your Jekyll site’s configuration variables can be found at the file called config.yml. You can fill out missing fields or replace unwanted variables completely, and it will look a lot like the code block below. 
    # Site Settings
baseurl: ""
url : "https://jennieablog.github.io"
# Blog Settings
theme_settings :
  title : "Jennie Ablog"
  favicon : "assets/favicon.ico"
# Profile Settings
profile :
  image : "assets/img/profile.jpg"
  username : "Jennie Ablog"
  description : "A BSc CS student who loves to teach herself a lot of stuff. 👩🏾‍💻"
  2. Once you’re already satisfied with the way it looks on your localhost, you can proceed to deployment to GitHub Pages.


4. Deploy your site to GitHub Pages.

  1. Fire up your terminal and navigate to your local git repository. 
    git add .
  2. Commit your changes. 
    git commit -m "initial commit for jekyll site"
  3. Push changes to master branch to deploy your site to GitHub pages. 
    git push origin master
  4. After a while, you can view your Jekyll Site running at [username].github.io.


5. Write your first blog post.

  1. Downloaded Jekyll themes usually come with sample blog posts which are located in a folder named posts/.
  2. Navigate to that folder. You will see files that are likely named in this format YYYY-MM-DD-sample-blog-post.md. When you open it it will look something like an html file except that it has something else in the beginning. 
    ---
layout: post
title: title
subtitle : subtitle
tags: [tag1, tag2]
author: 
comments : 
---

  3. What you see in the beginning of the file is called a yaml Front Matter block. Between the triple-dashed lines, you can set predefined variables or even define your own. They will then be made available for access using Liquid tags in the file. For more information on Front Matter, visit this page.

  4. After writing your blog post, you can git commit and git push again to the master branch of your git repository. Your website shall be updated accordingly.

When in doubt, you can always consult the Jekyll documentation, or the README.md of the GitHub repository of your chosen Jekyll theme, like this one or this one.


Well done! 🙆🏽‍♀️

You now have your own portfolio/blog website hosted for free for-ever!