The Missing Manual For Github Pages

Blog — a living fossil on the internet. Nowadays, people are immersed in short videos, let alone images and tweets. For writers striving for impact, social publishing platforms like Medium would be a better choice. But in the eyes of engineers, their code syntax highlighting sucks, and provide only limited config options. That’s why I can’t give up on a stand-alone blog. However, renting a VPS or using a cloud platform is breaking a butterfly on the wheel. Github Pages is just fine, though its document is a mess.

Launch your blog with a remote theme

  1. Create an empty repo named <your Github username> on Github as your blog repo. Don’t fork a theme repo as your blog ¹.
  2. Choose a Jekyll theme on Github. Remember, it should be a gem-based theme ².
  3. Fork it so you won’t be surprised when the author’s done something crazy ³. Now you get a <your Github username>/<theme name> as your theme repo.
  4. Copy _config.yml, Gemfile and index.html from your theme repo to your blog repo. Add remote_theme: <your Github username>/<theme name> in _config.yml; add jekyll-remote-theme to the plugins section of _config.yml; add gem “jekyll-remote-theme” in Gemfile.
  5. Add a _posts folder in your blog repo for articles. You can add markdown files named like 2021–01–

Now a personal blog is served at <your Github username> If you want to specify a custom domain, go to your blog repo’s settings on Github.

Customize your blog and test it locally

You can clone your blog repo to the local computer, and then install bundler to manage gems locally:

  • Executing bundle exec jekyll serve in the blog repo could preview the blog on your laptop.
  • If there is an error, fix them according to the error message.
  • Edit _config.yml to configure options.
  • Create folders and files with the same name as in your theme repo to override them as you please.

[1] It will be very hard if you want to change that afterward. And it’s better to separate your content from the presentation.

[2] Usually, this kind of theme has an assets folder to store CSS and Javascript files.

[3] You can always sync updates from the original repo.

Cross-posted on My Personal Tech Blog.

Senior Software Engineer at Indeed.