This article will teach you how to build a free personal website or blog. I will provide useful links to you rather than teaching you every details because some online tutorials are outdated.

1 GitHub Pages

GitHub Pages are public web pages for users, organizations, and repositories, that are freely hosted on GitHub’s github.io domain or on a custom domain name of your choice. Notice that we can only deploy static pages on Github Pages.

If you can follow the official tutorial Creating a GitHub Pages site with Jekyll and find it is easy to understand, you can skip section 1.1 and 2.1.

1.1 Hello World

Go to GitHub Pages and follow the tutorial. This may take 5 minutes if you are familiar with Github. Here I just copy some critical instructions from the tutorial.

  1. Create a new GitHub public repository named <username>.github.io, where username is your Github username.
  2. Clone the repository to your local file system.
  3. Enter the project folder and add an index.html file with "Hello World" in it.
  4. Add, commit, and push your changes. Go to your repository and wait for the build process to finish.

Now you should be able to see "Hello World" in https://<username>.github.io.

2 Jekyll

Jekyll is a static site generator. It takes text written in your favorite markup language and uses layouts to create a static website. You can tweak the site’s look and feel, URLs, the data displayed on the page, and more. Github recommend we use Jekyll to build our Github pages.

2.1 Jekyll Toy Example

Follow the Jekyll Quickstart and Step by Step Tutorial to learn basic Jekyll. This may take 20 minutes.

2.2 Start to Build

Now we want a personal blog. The easiest way is to find your favorite template in jekyll existing sites list and fork the repo. After you clone it to your local repository, don’t forget to modify _config.yml. There’re many beautiful exmaples on Github, find them!

And of course, you can fork my website so that you can skip following sections!

2.3 Add Tags

If you want to add tags to each of your post/article and provide a tag filter for users, follow this Tags in jekyll + Github Tutorial. This may take 10-15 minustes.

2.4 Add Comment Widget

You might be wondering, how is it possible to have a comment widget when it’s a static website.

Option 1: Github Issues make this possible! Follow utteranc tutorial so that you can add comment widget to every post! In order to make comments, users need to log in with their Github account.

Option 2: Disqus provide a comment widget that support upvotes and nested comments. In order to make comments, users should log in with their Google, Twitter or Facebook account.

My About page is using utteranc and my posts pages are using Disqus. Choose whatever you like.

3 Want Your Blog To Be Popular?

You need to make your blog appear on Google search results. Here is a great tutorial, which will teach you how to verify your website and upload sitemap.

Also, follow Google Guide: Help Google understand your content so that more people can find your blog and articles.

3.2 Analyze Your Blog

You want to see how many people visit your blog and what they are doing when they are in your website. Google Analytics can help us. Here are some main steps: Go to Google Analytics.

Create Google analytics account.

Find your Analytics Property ID. It should look like: “UA-XXXXXX-X” or “G-XXXXXXX.”

Create a file google-analytics.html in your _includes folder. Add the code snippet:

<!-- Global site tag (gtag.js) - Google Analytics -->
<script
  async
  src="https://www.googletagmanager.com/gtag/js?id=G-2LFZDRY4E8"
></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag() {
    dataLayer.push(arguments);
  }
  gtag("js", new Date());
  gtag("config", "G-2LFZDRY4E8");
</script>

Add this line into your _config.yml:

google_analytics: <Your ID, for example G-XXXXXXX>

Add this code snippet into the <head> tag of your website.

{% if site.google_analytics and jekyll.environment == 'production' %}
{% include google-analytics.html %}
{% endif %}

Git push, wait for build.

Go back to Google Analytics. Try visiting your blog and then Google Analytics should show that there’s one visitor to your blog.

3.3 Chinese User?

Github pages can’t appear in Baidu search results because Baidu is banned by Github. Here’re some easy solutions.

4 More Features

4.1 Code Syntax Highlighting

See my tutorial Syntax highlighting with Rouge in Jekyll.

4.2 Add Table of Contents

4.2.1 Basic TOC

We can use Jekyll built-in TOC generator! Just add following code into your markdown file:

- TOC
  {:toc}

It will generate a table of contents for your post. See my post C++ Interview Note as an example.

4.2.2 Customizable TOC

The above method is not customizable, since it is static, and the element is in the post content, so it is hard to make it as a sidebar.

What we want is: (1) customizable, (2) automatically highlight the current section, (3) as a sidebar.

See my tutorial: Automated Table of Contents for Jekyll with Highlighting.

4.3 Add Dark/Light Mode Switch

If you are using Disqus to generate comment widget, I would recommend you write css code to generate a dark mode. You can check my css files on how to do it.

If you don’t use Disqus, then there’s a tool called Darkreader that can automatically generate a dark mode for your website.

The reason is, Darkreader doesn’t work properly with Disqus. See my post about this Do not use Darkreader and Disqus at the same time

I’m using Simple-Jekyll-Search and this tutorial may help you.

End

If you have any questions or want to share your thoughts, please leave a comment. I will be notified via email:)