How to Build a Personal Website on GitHub Pages

GitHub Pages on a blue backgroundWhether you're looking to build a personal website or want to build a simple portfolio, GitHub Pages is one of the good options for the same. You don't need an expensive paid hosting platform to build such a kind of website. The following step-by-step tutorial with help you build a simple personal website which can be further extended, enhanced or improved as per your requirements. All you need is an active GitHub account with basic CSS and HTML skills. Beforehand knowledge of Markdown syntax will be icing on the cake. Though deep knowledge of Git is not a mandatory requirement, familiarity with its basics can certainly help. In case, you are looking to build a full-fledged business website, I'll strongly suggest looking for other options. GitHub Pages platform is free to use and gives liberal bandwidth covering the needs of almost 99% personal websites. It's best suited for freelancers and professionals. Let's not wait further and make a sparkling new personal website on the flexible GitHub Pages platform.

GitHub Pages on a blue background If you already have a personal website on a paid platform, this is an ideal time to make a switch. Unless you have a huge content archive, the transfer process should not be—much of a hassle.

Read Also:
Powerful Static Site Generators for Developing Custom Websites

If you haven't yet signed up for a GitHub account, go and get one—now! Let's get started and go through all the steps of creating a personal website with minimum efforts.

Prepare the Essentials Before Site Creation

Now that your GitHub account is in place, it's time to go ahead with the initial setup to kickstart the process. We'll start with installing GitHub Desktop on your computer.

Though the command line environment can be used, we'll use the GUI to ease the process. In case, you're already familiar with Git and the command line environment, go for it skipping the GUI path.

Now head over to your GitHub account and create a new repository with the following settings.

New repository creation on GitHub platform Make sure the repository name starts with your GitHub username and ends with with no blank or whitespaces in between.

Keep the repository—public. If you have a free GitHub account, GitHub Pages will not work if you make the repository—private. If it's going to be a simple personal site, public data should not be a big issue.

It's a good practice to create a default README file. You can later edit it manually to provide more descriptive information about the repository contents.

Add a license (optional) file and a .gitignore file for the Jekyll platform. It's a static site generator we'll use to power our personal website on GitHub Pages.

Sample .gitignore file for Jekyll What's this .gitignore file and why is it needed? In simple words, this file contains a list of files and directories that are ignored by the Git version control system.

For example, _site/ is the directory where the static site's content is written each time the website is modified. Therefore, there is no need to version-control it. This directory should be included in the .gitignore file. You can see other files and directories (see image above) as well which can be ignored.

Finally, click the 'Create repository' button to prepare the base for our personal website.

Add a Jekyll Theme and Configure the Essentials

Now that our website's repository is ready with the basic settings, let's move ahead and quickly add a Jekyll theme to it to kick start the site's design and customization process.

There are two ways to add a Jekyll theme to the repository. Either design it from scratch or add a readymade template and extend it further as per needs. To ease the entire process, we'll use the latter approach picking one of the pre-existing templates.

To get started, go to the Settings tab, scroll down on the page to reach the GitHub Pages section. Click the Choose a theme button to select a template which more or less match with your preferences.

Jekyll theme choosing button You can finish the theme selection process by selecting and clicking on one of the theme previews followed by a click on the Select theme button.

Selection process of a Jekyll theme For demo purpose, we've selected the Minimal theme from the list. You're of course free to choose your preferred template. Finish this step by clicking the Commit changes button.

A green color button If you open your website at this stage, you'll notice that the contents of the file is displayed on the homepage. There's another important file _config.yml created automatically during the theme integration process.

The file _config.yml contains the global site configuration options that are applied on the site. For example, you can define a custom permalink structure—through this file.

At this point, the current theme's name is already added to this file. Let's add a few useful options to this file to further customize the environment of our site. Click on this file's link in your repository followed by a click on the pencil icon present on the right side of the file editor.

Thereafter, below the theme name, add the following options and edit them—wherever required.

permalink: /:categories/:year/:month/:title/
title: My Awesome Site's Title
description: Description of my website
Do not forget to commit the changes after adding the options. If you're adventurous, you can try out other configuration options too. The updated file may look something like this.

Contents of a Jekyll configuration file The configuration options added to the file are as follows.
  • permalink: This option configures the URL structure of the posts published on the website.
  • title: Specify the website's title through this option.
  • description: Provide a short description of the website through this option.
This finishes the basic and initial setup of our website.

Add Content Layout and Design Options

Next, we'll add a file that'll help us in adding custom CSS to modify or enhance the design of the site. If you're happy with the existing template, you can skip this step.

Within the repository, create a file /assets/css/style.scss and add the following code snippet in it.


@import "{{ site.theme }}";
The import statement within this file will pull the default CSS rules for the theme. Right below this line, you can write your own custom CSS rules.

If you want to customize the default HTML layout too, create a file /_layouts/default.html and add this HTML markup to it. Use the Raw button to easily copy the code.

Thereafter, add a file /_layouts/post.html to the repository. Add the following code to this file.

layout: default

<small>{{ | date: "%-d %B %Y" }}</small>
<h1>{{ page.title }}</h1>

<p class="view">by {{ | default: }}</p>


{% if page.tags %}
  <small>tags: <em>{{ page.tags | join: "</em> - <em>" }}</em></small>
{% endif %}
This file includes the default template for post pages. Feel free to edit and customize it as per your needs. The layout code uses Liquid template language which is quite easy-to-learn.

Now that the posts' template is ready, create a _posts/ directory where the posts' files will reside. Because, Git doesn't allow empty directories, create a _posts/ file which can be deleted after the directory is in place and you've created at least one blog post file in it.

Create a index.html file and add the following snippet to it.

layout: default
The snippet will add the default header and footer to the homepage. Right below this snippet, you can specify the content section of the homepage in the form of custom HTML code.

Add Custom Domain with HTTPS Support

By default, your website resides on a subdomain. Fortunately, you can easily use a custom domain with HTTPS for your brand-new website.

The process is as follows. Go to the Settings → GitHub Pages → Custom domain option. Add your custom domain in the text field and click the Save button.

Custom domain for GitHub Pages Thereafter you need to add four A records to your domain name's DNS zone file. If you do not know how to do it, consult your domain registrar's help documentation or contact the support department. Following are the four A records which need to be added.

Record Type    Hostname    Value              TTL
-----------    --------    ---------------    ---------
    A             @    Automatic
    A             @    Automatic
    A             @    Automatic
    A             @    Automatic
Propagation of DNS records takes anywhere between 24 to 48 hours. To confirm whether your applied A records are in place and have propagated, use the following command at the command prompt.

dig +noall +answer
Windows 10 users can use the Bash on Windows command prompt for the same. Once this step is completed, it's time to make sure that your custom-domain powered site is served correctly on HTTPS URLs. To ensure that, complete the following simple configuration.

HTTPS enforcement for GitHub Pages Go to the Settings → GitHub Pages → Enforce HTTPS option and click the check box as indicated in the image above. This completes the custom domain configuration and HTTPS enforcement process.

Because you have complete control over HTML and CSS files, you can add just about anything to the pages. For more customization, you can read the Jekyll documentation.