How to set up your personal Blog using GitHub Pages

2 minute read

Header

First steps

Since it is quite recent that I managed to set up this blog on GitHub Pages, I’d like to take the opportunity to share how to setup your own site there.

GitHub Pages allows for publishing sites hosted on GitHub.io. You can create your personal blog, your company’s web site or your favorite project’s documentation, just follow these instructions [1] to create a special repository named username.github.io, as I did to create this personal blog. This repository must be public, no private repositories can be used to publish on GitHub Pages.

Once you have this repository you can clone it:

git clone https://github.com/username/username.github.com

And work on it as any other Git repository.

For example:

echo "Hi there" > index.html
git add --all
git commit -m "Initial commit"
git push -u origin main

How does it work?

As you can see, GitHub Pages is an easy way to create static sites by using a developer friendly tool like Git, and that is its main value proposition against other alternatives to build static sites: plain text, markdown syntax, no hassles and straight to the point. GitHub Pages uses Jekyll [2] behind the scenes to transform those plain texts files into an appealing site by taking care of things like layouts, styles, responsiveness, permalinks, categories, etc. This transformation takes place with every new commit on the associated repository.

Jekyll themes

GitHub Pages offers some Jekyll themes that you can choose from the first time you create the repository.

At this point, if you want to take advantage of GitHub Pages and Jekyll to create something more advanced that a couple of HTML pages, I recommend to install one of the many Jekyll’s theme available, i.e. [3]. Jekyll themes are ready to use templates that allow to create a professional-look site within minutes. There are themes to create personal portfolios, landing page for your business, blogs, project’s documentation, etc. Most of those themes are offered as Git repositories hosted on GitHub, so, once you chose your theme, the easiest way to use it and customize it is to fork that repository on your own repository.

I use Minimal Mistakes as the theme for this blog. Each theme has its own features, but most of them bring you:

  • Compatible with GitHub Pages.
  • Support for Jekyll’s built-in Sass/SCSS preprocessor.
  • Skins
  • Responsive layouts
  • Optimized for search engines
  • Optional header images, custom sidebars, table of contents, galleries, related posts, breadcrumb links, navigation lists, etc.
  • Plugins
  • etc.

How to test your page locally

As mentioned, the static site hosted on GitHub Pages is rebuilt with every commit made against the username.github.io repository that you are going to edit locally, so it is very easy to update your site, even using the GitHub’s integrated IDE named Codespaces, but sometimes is more convenient to test your changes locally before committing to the repository and make those changes public. To start your Jekyll server locally just type the following on your repository (once you cloned a Jekyll theme repo):

gem install bundler jekyll
bundle exec jekyll serve

Jekyll allows for building a site from scratch as well by typing:

gem install bundler jekyll
jekyll new my-awesome-site
cd my-awesome-site
bundle exec jekyll serve

Now browse to http://localhost:4000

The server is always monitoring the local folder for changes to update instantly.

You may also enjoy