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:
- 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 ¹.
- Choose a Jekyll theme on Github. Remember, it should be a gem-based theme ².
- 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.
- 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; addjekyll-remote-themeto the plugins section of _config.yml; addgem “jekyll-remote-theme”in Gemfile. - Add a _posts folder in your blog repo for articles. You can add markdown files named like
2021–01–03-Hello-World.md.
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 servein 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.
