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

First of all, you definitely want beautiful Jekyll themes on Github instead of boring default themes. But the official “Creating a Github Pages site with Jekyll” leads you down the wrong path — You don’t need to create a new site in your repo using Jekyll or bundle because this will generate useless stuff from a default theme. You only need 5 steps:

  1. Create an empty repo named <your Github username>.github.io on Github as your blog repo. Don’t fork a theme repo as your blog ¹.

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

Customize your blog and test it locally

In general, the above steps would be enough. But every theme may have its particular problems, and you need to customize the blog title and other stuff soon — push to Github every time for testing is time-consuming.

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.

[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.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store