The Missing Manual For Github Pages

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–

Customize your blog and test it 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.



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
Chao Yang

Chao Yang

Senior Software Engineer at Indeed.