In this post, I’ll show you how to create a website based on Github Pages and Jekyll very quickly. You have also a lot of available beautiful themes to choose in different categories.

TL;DR

  1. Create a Github account, for example, yourAccount.
  2. Create a new repository with the name exactly is yourAccount.github.io (this’s also your website’s url).
  3. Download Github Desktop (Windows, MacOS) or Gitkraken (Linux) or just use command lines if you know git.
  4. Clone above repository to your local machine using Git client or command lines. A new folder named yourAccount.github.io will be created on your machine.
  5. Choose a theme you like from this site.
  6. Copy all files and folders from zip file downloaded in step 5 to folder in step 4.
  7. Modify file _config.yml with your own informations. The must-be-modified line is url: yourAccount.github.io
  8. Push all changes to Github.
  9. Wait some minutes and browse https://yourAccount.github.io to see your wonderfull website.

All main steps

Create a free Github account and sign in. Don’t forget to verify your email address. Suppose that, I created an account whose name is yourAccount.

Create a new repository. This repo will contain all of your website’s source codes.

  1. Sign in to Github with account yourAccount.
  2. Go to the home page and click on New button on the right hand side of field Repositories.
  3. Name your repository exactly with yourAccount.github.io where yourAccount is your Github account name. This step is very important, if you choose another name, it cannot work!
  4. You can give some details on the Description field, choose Publish or Private your repo (you need to pay if you want to choose Private). With a private repo, people cannot see your website’s source codes.
  5. After you finish to create your repo and done all of following steps. Your website will available at https://yourAccount.github.io.

Use git or download git client. You need to clone your repo to your local machine so that you can modify your website’s files easily. Before doing this on the next step, you need to know about git, if you don’t, you can use a git client like Github Desktop or Gitkraken. I advice you to choose Github Desktop if you use Windows or Mac and choose Gitkraken if you use Linux.

Even if you don’t know anything about git and don’t want to use a git client, you can follow below basic git commands just for this purpose.

Below are very simple git commands, if you have something complicated, please let me know in the comment section below this post.

  • Be sure that you have already installed git on your system.
  • You need a terminal app to use the git codes. I recommend cmder (Windows), guake (Linux) and iTerm2 (MacOS).

  • Provide your info to git. It’s useful for the first time, you don’t need to provide them every time you push to Github remote.

    git config --global user.name "Anh-Thi Dinh"
git config --global user.email "[email protected]" # your email to register to Github

  • In the case you have many git accounts, you have to provide your account and password every time you contact to the git remote. Below line will help you remember your git info for the working repo,

    git config credential.helper store

  • Clone your repo by git command. Go to your repo’s website (https://github.com/yourAccount/yourAccount.github.io), click on the green button named Clone or download and then choose Clone with HTTPS. Copy the link below it, i.e.

    https://github.com/yourAccount/yourAccount.github.io.git

  • In the terminal, cd to the directory where you want to store your repo,

    cd <full-path-contains-your-repo-folder>

    and then use below line of code

    git clone https://github.com/yourAccount/yourAccount.github.io.git

    You may be asked to fill your Github account & password.

Afterall, a folder named yourAccount.github.io will appear on your directory. Don’t forget this folder because you will work on it every time.

Using git clients. If you like to use git command lines, please read the previous steps. For both Github Desktop and Gitkraken, you need to focus on their 4 functions: clone (copy entire repo from the remote for the first time), commit (claim the changes), push (send to remote) and pull (update changes from the remote to local).

  1. Install, open Github Desktop (GD) and then log in with your Github accout (yourAccount).
  2. Go to your repo’s website (https://github.com/yourAccount/yourAccount.github.io), click on the button Set up in Desktop, GD’s windows will open up.
  3. In the section Local path, choose wherever you want to store your repo on your local system and then click on Clone.
  4. Open up the directory you use to store github on your computer, a new folder is created whose name is yourAccount.github.io.
  1. Install, open Gitkraken.
  2. File > Preferences > Authentication > choose tab GitHub.com and then log in with your Github account (yourAccount).
  3. File > Clone Repo > Clone > GitHub.com > in the list of Repository to clone, you choose yourAccount.github.io; in section Where to clone to, you choose a place on your computer to store your repo. Finally, press Clone the repo.

Find and choose a Jekyll theme. There are several websites which give free Jekyll themes such as this site.

Extract & copy files. Normally, the theme you downloaded is contained in a .zip file. You need to extract all of your contents to the repo’s directory. (Extract to folder > copy all files in the extracted folder > paste to the repo’s directory).If everything goes right, your repo’s direct to will be like

| yourAccount.github.io
|--- # some folders & files
|--- _layouts
|--- _posts
|--- _config.yml
|--- index.html
|--- # some folders & files

Modifying _config.yml file. Open up file _config.yml inside folder yourAccount.github.io and edit it with your own information. It depends on the theme you downloaded but every theme will have some common settings as giving below,

  • title: Your website’s name, for example, The first website.
  • description: Your website’s description
  • baseurl: leave it blank (see more on the Advanced settings section)
  • url (the most important): https://yourAccount.github.io (don’t forget I have supposed that your Github account is yourAccount)

There are many other fields which are important for the specific theme. They are usually described carefully by the author of these theme, just follow the guides.

Push to Github remote. Every time you finish editing your files inside the folder yourAccount.github.io, you need to push them to the Github remote. You can use git commands or a git client.

Remeber 4 keywords add, commit, push and pull when working with a git command. Use the following lines (don’t use any texts beginning with #)

# add all changes to stage
git add *
# alternative to above line if you add a specific file or files
git add <name-of-file> 

# commit the changes (ready to push)
# you can ignore <name-of-file> to include all changes
git commit -m "<some-comments-about-the-commit>" <name-of-file>

# push to remote
git push origin master

If you want to “pull” the contents from the remote repo to the local repo (in the situation that you use different computers for the same repo and you pushed from some computer and want to get the update to other one)

git pull origin master

GD will automatically recognize the changes in the repo directory and display all notifications on the left panel of its window.

  • In the field Summary, you must give a brief description of the changes.
  • In the field Description, you can give some more details about the changes but it’s optional.

After that, click on Commit to master and then press the button Publish (on the top right).

Like GD, it also automatically recognize the changes in your repo directory. The changes will be displayed on the right panel of its window.

  • Click on Stage all changes to bring all changes to the stage status (ready to commit). You can only a specific file by click Stage file on the right of this file (you need to mouse over this file to see the button)
  • After staging, give a summary about the changes in field Summary (it’s mandatory) and more details in field Description (it’s optional)

Afterall, click on Commit button and then press Push (on the top bar) to send all changes to the Github remote.

Make your own a cup of coffee, wait a few minutes and then browse https://yourAccount.github.io to see your masterpiece.

Advanced settings

Above guide only helps you make a site based on your account name, i.e. <your-account>.github.io. That’s why at step 2, you create a repo on branch master. If you intend to create multiple websites also based on Github Pages and Jekyll, don’t worry that you have to make multiple Github accounts for this purpose.

Github supports making a gh-pages branch repo to serve a project’s website. It means that you can use gh-pages branch repos to store your websites without the need of the same name with url. More specifically, you can create a repo named first-site, store all your codes like above guide showing you and then browse the website at https://<your-account>.github.io/first-site. It’s cool, right? In order to do that,

  1. At step 2, you can create a repo with any name you want, for example, first-site.
  2. Go to that repo’s url (https://github.com/yourAccount/first-site)
  3. Click on Branch: master (on the left) > Fill in Find or create a branch by gh-pages.
  4. Follow the same manners as above guide to clone your repo to your local machine. At the step of using git commands or git client, you make more below step
    • Git command: Type in terminal git checkout gh-pages to change from the branch master to branch gh-pages.
    • Github Desktop: Look at the top bar, click on Current Branch and choose gh-pages on the dropdown list.
    • Gitkraken: On the top left bar, right beside first-name tab, choose gh-pages instead of master.
  5. Everything else will be the same as above guide except step 7 when you modify the _config.yml file.
    • baseurl: /first-site (because now your site presents at yourAccount.github.io/first-site instead of yourAccount.github.io.
  6. Your website is now available at https://yourAccount.github.io/first-site.