How do I build my first homepage with GitHub Pages and Gatsby

Canhua Li
4 min readDec 5, 2021

Last week, I built my home page with Gatsby and GitHub Pages. This article only shares how the tools are chosen and what kind of problem I met. If you want a step by step tutorial, please go directly to How Gatsby Works with GitHub Pages because Gatsby already provides a very good document.

Here is my final home page, which includes three sub pages: Blogs, GitHub Projects and Profile:
Home Page
My GitHub Projects


As a developer in Microsoft, I write a lot of codes, and I have a lot of GitHub projects. But I never built a home page for myself. I used GitHub, Linkedin, and medium, and I want a space for me to combine them together to share myself. Here are several high level features I came up:

  • Blogs. Where I can share the problems and solutions I hit.
  • GitHub Projects. Where I made a introduction to the collection of my projects.
  • Profile. A short introduction to myself.
  • Customization. I want the visual and layout be fully controlled by myself.

Web Hosting

The first tool comes to my mind is GitHub Pages. The best feature I lover is: Free hosting with >95% uptime. I post Selenium-automation by licanhua on GitHub Pages more than 5 years ago, and I’m still able to access it.

Free static-site generator

I did some research, and there are three popular free JS frameworks: hexo, Gatsby and nextjs. hexo is the tool I used in Adaptive Cards. I want try something new, so I dropped hexo. Both Gatsby and nextjs are React framework, and they are easy to use. CRA vs Next.js vs Gatsby — Comparison and How to Choose One ( provides a good comparison even if you didn’t dig into it. Because I have no plan to host a server by myself, so Gatsby is enough for me. So just take it.


Follows gatsby-starter-blog: Gatsby Starter | Gatsby (, I create my first version of blogs in half an hour. Everything works very smoothly, and it’s very cool.


In the plugins, @wkocjan/gatsby-theme-intro | Gatsby ( came into my eyes, and it’s definitely the things I’m looking for. After 20 minutes, the draft version is ready. Then I start the customization, and troubles began.

  • Issue 1 — Shadowing doesn’t work very well

The first customization is to remove the Contact form. I don’t need it.

Remove Contact
Remove Contact

I really loves the feature of Shadowing in Gatsby Themes | Gatsby (, it allows me to replace any src/ in plugin like a piece of cake. The plugin promised to be able do it too, but actually it’s not. I believe it’s related to the name of @wkocjan/gatsby-theme-intro. If you want the plugin works, you may stick with one layout of project name. For example: gatsby-theme-intro`. When I shadow the any of the files in /src, ../components/custom-fonts/custom-fontscode can’t be resolved:

import CustomFonts from "../components/custom-fonts/custom-fonts"

I worked-around the issue with

import CustomFonts from "@wkocjan/gatsby-theme-intro/src/components/custom-fonts/custom-fonts"

I’m like to make blogs, profiles in the same projects. I successfully made it, but I found the blog is in ‘compact mode’. “Setup the profile folder locally” is <h1>, but it looks like normal text.

Spacing issue in blogs
bad spacing after mixing two plugs in the same project

After investigating, I found that the problem is introduced by my 2nd plugin. @wkocjan/gatsby-theme-intro used TailwindCSS. Because the webpack is not that smart(Maybe I didn’t find the right solution) enough, it make my blogs applied TaiwindCSS too.

Instead of union /blogs and /profile into one source repo, I split it into two repos. So each one will work independently.

My GitHub Projects

After digging, two plugins are selected: gatsby-theme-apollo-docs | Gatsby ( and smooth-doc | Gatsby (

I chose smooth-doc just because I failed on the first step when I create the website with `npx gatsby-cli new website`. I spent a lot of time to make it right.

If you want to use smooth-doc plugin, it saves your time to clone smooth-doc/website at main · gregberge/smooth-doc ( directly.

Gotha for Gatsby

  • If multiple plugins are consolidated into the same project, pay attention to the css technoledge they are using. TailwindCSS, bootstrap and other style framework may conflicts with each other.
  • Gatsby provides thousands of plugins. To save my time, I always skip the plugin which doesn’t have demo link.
  • Pay attention to plugin name like @wkocjan/gatsby-theme-intro which have two lays. Shadowing may not work. (My statement may not be true, try shadow a simple component before you adopt it)


demo: All posts | Canhua’s Blog (

/blogs source code: licanhua/ Canhua’s Home Page

/profile source code: licanhua/profile: Profile (

/github-project source code: licanhua/github-projects