Blogging with Jekyll and GitHub Pages
I recently switched my blog to Jekyll and GitHub pages. I started blogging last year and went for WordPress without thinking too much about it. But I’m happy with the change and wanted to share the setup as my first article here.
GitHub Pages is a static site hosting service, designed to host pages directly from a GitHub repository. It is based on Jekyll.
Jekyll is an open-platform, blog-aware, static site generator written in Ruby. It basically transforms plain-text files into a website, interpreting Markdown and Liquid
Blogging with Jekyll and GitHub Pages is nice because:
- It’s free
- It’s open-source
- Markdown is fantastic for text editing
- My notebooks, scripts and blog articles are now all on GitHub
- It only takes a few minutes to create a blog, and modifications are easy
Create your first Blog using Jekyll
To begin with, Jekyll and its prerequisites needs to be installed on your computer. If you are using Windows, Jekyll is not officially supported but you can make it work following the instructions [here][jekyllwin]. Otherwise:
- Install Ruby or check your version with
ruby -v
in a terminal - Install RubyGems, the Ruby package manager, or check your version with
gem -v
- Install GCC and Make, or check you version with
gcc -v
andmake -v
- Now you can install Jekyll and Bundler by running
gem install jekyll bundler
Once you are all set up, it is time to actually create the blog. Open your terminal, go the the folder of your choice and run:
# Create the Jekyll site in current folder
jekyll new .
# Build the site on the preview server
jekyll serve
Here is how the folder and the terminal should look like:
As you can see, Jekyll created the needed files in your folder. Going to http://127.0.0.1:4000/
on your browser should show the following:
This is it! You created your first blog, congratulations! It is a simple, un-themed version only hosted locally for now. The goal is to understand the main architecture and important files here.
By modifying config.yml
, you can edit the principal information of the newly created site, such as adding your name and the name of the blog, or create a description.
The _posts
directory is for all the articles. You want to publish a new blog post? Just create your Markdown file and put it here.
Make it shine
You now have the basics of Jekyll, including Blog creation, local rendering and file browsing. Let’s see how to obtain something even more pleasant to the eyes of your future readers.
An very interesting feature of Jekyll is the themes. A theme can change the fonts, the main page layout, the navigation menu of the blog, etc. A quick google search should help you find the perfect theme. Here are some availables at Jekyllthemes:
Once you found the theme you like, check its documentation on GitHub. Sometimes it can be installed in a few seconds and two lines of codes using Gem:
- Add
gem YOUR_THEME_NAME
toGemfile
` - Add
theme: YOUR_THEME_NAME
to_config.yml
- Run
bundle
in your terminal
Otherwise, you can go on the GitHub repository of the theme and clone it locally. In that case, the content of the theme will constitute your blog’s base. Meaning you have to clone the repository in a new, empty folder with the following code on your terminal:
# Go to the folder you want to clone the theme in
cd blog
# Clone the git repository
git clone https://github.com/YOUR-THEME-REPOSITORY
From here, you can do a bit of cleaning by removing the example markdown files of the articles in _posts
, and modify the config.yml
. I encourage you to read the configuration file and GitHub documentation entirely, as some themes provides different functionalities.
Publish it with GitHub Pages
Time to show your creation to the world! This is where GitHub Pages comes in.
Go to your GitHub profile (or create one), and create a new repository called YOUR_USERNAME.github.io
. This repository will be linked to your local blog file.
Then (install git and) open the terminal in your blog directory and type:
# Create a git repository from your folder
git init
# Add all the files to the git repo
git add .
# Commit the changes to the repo
# git commit -m "first commit"
# Add your GitHub repository as remote origin
git remote add origin remote repository git@github:YOUR_USERNAME/YOUR_USERNAME.github.io
# Push your local repository content to GitHub
git push -u origin master
From here, all the content of your blog folder will be uploaded to your GitHub repository. You have nothing else to do! Github Pages will render your blog at the address YOUR_USERNAME.github.io
.
To dig deeper or if you encounter any problem during the process, you can check the official documentations of Jekyll, GitHub Pages and Git