Build a Blog on GitHub Pages Using Jekyll

Choose your solution

There are varies ways to creat your personal website. Without comparing their pros and cons, here lists some popular platforms and frameworks that people use widely:

Platforms:

Frameworks:

In this article I will show how to use jekyll generating webpages, and use GitHub Pages to host sites.

Introduction

Why GitHub Pages

GitHub is an online project hosting platform using Git. More than 11 million people use GitHub to discover, fork, and contribute to over 29 million projects. GitHub offers both plans for private and free repositories on the same account which are commonly used to host open-source software projects.

GitHub Pages is a static site hosting service provided by GitHub.GitHub Pages is designed to host your personal, organization, or project pages directly from a GitHub repository. Compared with other services, you don’t need to rent a server, or deal with databases, even know a lot about HTML. Pages Help offers wizzard guiding you publish your pages. All you need to do is to put these codes into a new repository, just like managing your other projects on GitHub. Most important, all these services are free.

On the homepage of GitHub Pages, there is video What is GitHub Pages? introducing GitHub Pages. And teach you how to build a hello-world page step by step.

What is Jekyll

Apart from simple HTML pages, GitHub Pages also provides a simple, blog-aware, static site generator: Jekyll. It takes a template directory containing raw text files in various formats, runs it through a converter (like Markdown) and our Liquid renderer, and spits out a complete, ready-to-publish static website suitable for serving with your favorite web server.

Since Jekyll is the default engine behind GitHub Pages,we can use Jekyll to host your project’s page, blog, or website from GitHub’s servers for free.

Visit Jekyll docs, which covers topics such as getting your site up and running, creating and managing your content, customizing the way your site works and looks and deploying to various environments.

Establishing development environment

You need to install Jekyll locally if you want to use it.

Jekyll is developed with Ruby. The best way to install Jekyll is via RubyGems. At the terminal prompt, simply run the following command to install Jekyll:

$ gem install jekyll

Since most themes need other gems supported, Bundler gems becomes necessary. The command becomes:

$ gem install jekyll bundler

It should be noted that MS Windows is not an officially-supported platform. What’s more, you will need to install Xcode and the Command-Line Tools if you are using macOS.

Visit Jekyll docs: Installation to learn more.

Creating sites

With Jekyll,you can create a new site by doing the following:

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

And then visit http://localhost:4000 to see your awesome site.

The Jekyll gem makes a jekyll executable available to you in your Terminal window. You can use this command in a number of ways:

$ jekyll build
# => The current folder will be generated into ./_site

$ jekyll build --destination <destination>
# => The current folder will be generated into <destination>

$ jekyll build --source <source> --destination <destination>
# => The <source> folder will be generated into <destination>

$ jekyll build --watch
# => The current folder will be generated into ./_site,
#    watched for changes, and regenerated automatically.

$ jekyll serve
# => A development server will run at http://localhost:4000/
# Auto-regeneration: enabled. Use `--no-watch` to disable.

$ jekyll serve --detach
# => Same as `jekyll serve` but will detach from the current terminal.
#    If you need to kill the server, you can `kill -9 1234` where "1234" is the PID.
#    If you cannot find the PID, then do, `ps aux | grep jekyll` and kill the instance.

$ jekyll serve --no-watch
# => Same as `jekyll serve` but will not watch for changes.

Use a theme

By default, the Jekyll site installed by jekyll new uses a gem-based theme called Minima. Apart from this, you can also download themes shared on the Internet. Here lists some popular platforms sharing Jekyll themes:

What’s more, you can also directly fork others’ pretty sites hosting on GitHub. Sites · jekyll/jekyll Wiki · GitHub lists lots of blogs made with Jekyll hosting on GitHub.

Visit Jekyll docs: Themes to learn more.

Writing posts

Finally, you can write something belong to you. Jekyll is, at its core, a text transformation engine. The concept behind the system is this: you give it text written in your favorite markup language, be that Markdown, Textile, or just plain HTML, and it churns that through a layout or a series of layout files.

Markdown

Markdown is a lightweight markup language with plain text formatting syntax designed so that it can be converted to HTML and many other formats using a tool by the same name. Markdown is often used to format readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor. Here are some quick start on Markdown syntax:

kramdown, a fast, pure-Ruby Markdown-superset converter, is Jekyll’s default Markdown language converter. What’s more, you can also find some advance functions that is not included in the original Markdown on kramdown Syntax, such as math equations, complex tables. Using Online Kramdown Editor, you can directly edit your article on a webpage.

If you are interested in writing papers or slides using markdown, you can follow Madoko project which is provided by MS Research.

Publish posts

One of Jekyll’s best aspects is that it is “blog aware”. What does this mean, exactly? Well, simply put, it means that blogging is baked into Jekyll’s functionality. If you write articles and publish them online, you can publish and maintain a blog simply by managing a folder of text-files on your computer.

A basic Jekyll site usually looks something like this:

.
├── _config.yml
├── _drafts
|   ├── begin-with-the-crazy-ideas.textile
|   └── on-simplicity-in-technology.markdown
├── _includes
|   ├── footer.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   ├── 2007-10-29-why-every-programmer-should-play-nethack.textile
|   └── 2009-04-26-barcamp-boston-4-roundup.textile
├── _site
├── .jekyll-metadata
└── index.html

Visit Jekyll docs: Directory structure to learn more.

Directory _posts is your dynamic content, so to speak. The naming convention of these files is important, and must follow the format: YEAR-MONTH-DAY-title.MARKUP. The permalinks can be customized for each post, but the date and markup language are determined solely by the file name.

To add new posts, simply add a file in the _posts directory that follows the convention YYYY-MM-DD-name-of-post.ext and includes the necessary front matter. Take a look at the source for this post to get an idea about how it works.

Visit Jekyll docs: Front Matter and Jekyll docs: Writing posts to learn more.

Deploying on GitHub Pages

If you have already tested your sites locally, you can upload your code to GitHub now!

If you are a user of GitHub, it will be quite easy for the next few steps. Just add a new repository with name ghname.github.io, where ghname is the ID of your GitHub account. Then put your site’s code into this repository. And voila! Your site will be automatically built. You can visit it following the link https://ghname.github.io.

$ git init
$ git clone http://github.com/ghname/ghname.github.io.git

$ git pull origin master

$ git add --all
$ git commit -m "leave a message"
$ git push origin master

Visit Jekyll docs: GitHub Pages to learn more.