Creating A Blog with GitHub Pages and Jekyll
I have written blogs before on existing web-based blogging platforms like Blogger and Tumblr, lots of them. For this website, I was looking for fewer features that I could fine-tune locally on my machine.
Keeping this in mind, GitHub Pages with Jekyll seemed like the best option. I’ve documented the process step-by-step in the form of a setup post, hoping it might help those who are looking to setup their own website.
Hosting - GitHub Pages
GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub, optionally runs the files through a build process, and publishes a website. Using GitHub Pages for hosting the website seemed ideal since I’m familiar with GitHub and already have repositories there.
Start by creating a repository with the name <username>.github.io, replacing <username> with your GitHub username. Next, we move on to creating the files for the wesbite.
Site Generator - Jekyll
To create your website, you can do it from scratch by creating HTML and CSS files for each part of your website, or automate the process using a static site generator. The pages are pre-built before publishing, which leads to faster loading times and a lightweight website.
Jekyll is one such site generator, which is the site generator used in GitHub Pages. It takes Markdown and HTML files and builds the website based on the layouts provided by the theme.
Local Setup
Setting up Jekyll requires Ruby and Git to be installed on your machine. Git is usually installed by default, and the instructions for installing Ruby on different operating systems can be found here.
Note: While installing Ruby on a Mac M1 machine, the build kept failing due to errors relating to OpenSSL. So if you’re facing a similar problem, adding the following environement variables before the install command should help.
$ export LDFLAGS="-L $(brew --prefix capstone)/lib" $ export CPPFLAGS="-I $(brew --prefix capstone)/include" $ export PKG_CONFIG_PATH="$(brew --prefix openssl@1.1)/lib/pkgconfig"
Once installation is complete, create your new website:
$ jekyll new <directory name>
This provides a base theme to begin with, however you can modify it to your needs, which will be discussed in the next section. You can run the blog locally by typing:
$ bundle exec jekyll serve --watch
Theme - jekyllBear
There are a couple of sites where you can find Jekyll themes, they are listed in the Jekyll documentation. After a lot of searching, I chose jekyllBear, a theme based on Bear Blog, a writing-focused blogging platform. It has few but important features, making it easy to manage and also add/tweak stuff in the future.
Using the installation instructions, I made changes to the required files in my website repository and added/modified files if required.
Additionally, you can make changes to the theme itself like modifying the CSS, adding syntax highlighting functionality or adding Jekyll plugins.
Add content
The theme provides some basic files to add content to, for example an index.md file for the home page, an about.md for the about page, and a _posts directory where you can create blog posts.
Create your first post by adding a file in the _posts directory with the following format: year-month-date-posttitle.md. You can use the sample posts that come with the theme to know what format to follow for the content.
Publish your website
Now that you have your content and theme ready, it’s time to publish your site to GitHub Pages. Firstly, if your repository is not initialized as a git repository by this stage, enter the following commands:
$ git init
$ git remote add origin https://github.com/<username>/<username>.github.io.git
This initializes the repository and adds the URL of where to push the commits to, which is your website repository.
Lastly, I wanted to publish only the files from the build of the site and not the source files. This gist explains on how to publish a subfolder to GitHub Pages. Based on it, I created a script to publish a post or update any part of the website.
#! /bin/bash
jekyll build
git add .
git commit -m "$1"
git subtree push --prefix _site origin main
jekyll build generates the website files and stores it in the _site directory. The files are added and a commit is made with a message of choice, entered as the first parameter when running the script (hence the $1). The git subtree command pushes the contents of the _site subfolder to GitHub.
$ chmod +x publish
$ ./publish "Initial commit"
Once the script is run, you can see the files in your repository. Once the build is complete on GitHub (a green tick should appear next to the recent commit’s hash), the content will appear on <username>.github.io.