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:
Overview
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 (coffeencoding.com) 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.
Blogs
Follows gatsby-starter-blog: Gatsby Starter | Gatsby (gatsbyjs.com), I create my first version of blogs in half an hour. Everything works very smoothly, and it’s very cool.
Profile
In the plugins, @wkocjan/gatsby-theme-intro | Gatsby (gatsbyjs.com) 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.
I really loves the feature of Shadowing in Gatsby Themes | Gatsby (gatsbyjs.com), 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"- Issue 2— Bad layout after mixing
@wkocjan/gatsby-theme-introand gatsby-starter-blog.
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.
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 (gatsbyjs.com) and smooth-doc | Gatsby (gatsbyjs.com).
I chose smooth-doc just because I failed on the first step when I create the website with `npx gatsby-cli new website https://github.com/gregberge/smooth-doc-starter`. 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 (github.com) 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-introwhich have two lays. Shadowing may not work. (My statement may not be true, try shadow a simple component before you adopt it)
Links
demo: All posts | Canhua’s Blog (licanhua.github.io)
/blogs source code: licanhua/licanhua.github.io: Canhua’s Home Page
/profile source code: licanhua/profile: Profile (github.com)
/github-project source code: licanhua/github-projects
