0%

First blog - Setting up my github pages blog with Hexo

Posted on Edited on Disqus:

Introduction

Github pages

Github pages is a github service that can host personal or project web pages directly from a github repository. This is ideal place to host my blog site because it is fast, and I will have a github.io domain, and there are some really cool blog frameworks that support deploying blog site to Github Pages.

Hexo

The most popular blog framework that supports github pages is Jekyll It seems, because it is officially recommended by github. But I found another framework Hexo, which compared to Jekyll, is similar but much easier to use, I only need to know 4 commands,

1
2
3
4
hexo n # new post
hexo g # generate
hexo s # server
hexo d # deploy

After I checked out some Hexo built blog sites, I decied to go with Hexo. Hexo is wirtten in node.js, and it supports a lot powerfull plugins and has cool themes.

Install Hexo

Follow Hexo doc

Set up Github Pages

Create github pages repository on github.com, the repository name is vmnet8.github.io where vmnet8 is my github account.

Install and configure Git which Hexo requires

Install git. I am coding and will be blogging on my Ubuntu Linux, to use Hexo to deploy my blog site to github pages, I need to install and configure git first. Install:

1
$ sudo apt install git

Configure git with github

1
2
3
$ git config --global user.name "Anna X"
$ git config --global user.email "vmnet8@gmail.com"
$ git config --list

Add my ssh public key to github. I will have Hexo deploy to github pages over ssh without asking username and password.

Install Node.js

Follow node.js doc
Install node.js using package manager - APT

1
2
$ curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
$ sudo apt install -y nodejs

As of 12/21/2017, node.js version is v8.9.3

1
2
$ node -v
v8.9.3

Install hexo-cli

Follow Hexo doc

1
sudo npm install -g hexo-cli

As of 12/21/2017, hexo version 3.4.3

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
$ hexo version
hexo: 3.4.3
hexo-cli: 1.0.4
os: Linux 4.4.0-103-generic linux x64
http_parser: 2.7.0
node: 8.9.3
v8: 6.1.534.48
uv: 1.15.0
zlib: 1.2.11
ares: 1.10.1-DEV
modules: 57
nghttp2: 1.25.0
openssl: 1.0.2n
icu: 59.1
unicode: 9.0
cldr: 31.0.1
tz: 2017b

Build my blog using Hexo

Initialize my blog folder

Follow Hexo setup doc, I use “vmnet8.github.io” as my blog folder.

1
2
3
$ hexo init vmnet8.github.io
$ cd vmnet.github.io/
$ npm install

Basic blog site configuration

Edit blog configuration file _config.yml in blog folder.

1
2
3
4
5
6
7
# Site
title: Anna's blog
subtitle: My tech blog
description:
author: Anna X
language: en
timezone: America/Los_Angeles

Note that when editing _config.yml file which is YAML format file, for key-value pairs format like “key: value”, there should be a space after “:”, same for sequence item, there should be a space after “-“

Create blog post using Hexo

Create my first blog post

1
2
$ hexo new "1st blog"
INFO  Created: ~/vmnet8.github.io/source/_posts/1st-blog.md

Edit the blog post file 1st-blog.md

1
$ vi source/_post/1st-blog.md

The blog post .md file is markdown format file with a header called “Front matter”

1
2
3
4
5
---
title: 1st blog
date: 2017-12-21 12:44:07
---
This is my first blog post.

The front matter is YAML format .
The blog content below front matter is markdown format which is a lightweight markup language with plain text formatting syntax. It is designed so that it can be converted to HTML.

When creating blog folder using “hexo init”, a sample blog post source/_posts/hello-world.md will be created automatically, you can cat it for reference.

Test blog post

Run “hexo g” to generate the static html files and “hexo server” to start http service on port 4000 for blog access.

1
2
3
4
$ hexo g
$ hexo s
INFO  Start processing
INFO  Hexo is running at http://localhost:4000/. Press Ctrl+C to stop.

Then go to http://localhost:4000/ in browser.
Notes:

  • Every time you run hexo command, you current dir should be the hexo blog folder.
  • Note: every time you make change to the configuration file or any page or post, you need to do “hexo g” to generate the new static html files. If something wrong happens due to wrong syntax in yml configuration file or md markdown file, you may need to do “hexo clean” and then “hexo g” to re-generate all blog html files.

Deploy blog to github pages

Follow Hexo deployment doc
Install git hexo deployer plugin.

1
npm install hexo-deployer-git --save

Note: When you install hexo module by “npm install –save”, your current dir should also be the blog fold.
Configure deployment to higthub, edit blog configuration file _config.yml in blog folder

1
2
3
4
deploy:
  type: git
  repo: git@github.com:vmnet8/vmnet8.github.io.git
  branch: master

I use ssh instead of https for my github pages repository access for Hexo, so I won’t need to enter username/password for deployment to github.
Deploy to github pages

1
$ hexo d

Then go to my github pages https://vmnet8.github.io in browser.