By

GitHub Pages and Hexo is a totally free, convenient yet powerful way to build your own blog. GitHub Pages gives the free space to host your blog contents; Hexo provides the blog schemes and designs for you to choose from, enables you to focus on writing the content with Markdown. And after editing a new article, simple Hexo commands help to generate the HTML content and deploy it into your blog. Plus, all your articles are under version control. If you would like to write a blog in a simple way and enjoy using Markdown and GitHub, this is the framework for you.

Here is a step-by-step guide on how to do this.
GitHub Pages

Setup GitHub Pages

  1. Get a GitHub account. Please note the blog url will be http://yourUsername.github.io.
  2. Create a new repository named yourUsername/yourUsername.github.io. Go to https://github.com/new and create it from there.

    Example: my GitHub account is named learncodingwithher and my repo is learncodingwithher/learncodingwithher.github.io.

Create the new repository

Install Git and Setup the SSH Key

  1. Install Git on your computer. On Mac, install it with Homebrew with this command in Terminal,
    brew install git

Tips: if you do not have Homebrew installed yet – install Xcode from App Store; and then run this command in Terminal to install Homebrew,
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

  1. Config Git,
    git config --global user.name "<your name>"
    git config --global user.email "<your email>"
  2. Generate a SSH key for GitHub,
    ls -al ~/.ssh
    rm -rf ~/.ssh/id_rsa*
    ssh-keygen -t rsa -C <your email>
    press enter at the prompt. Note the email address here is the one associated with the GitHub account. This step creates a SSH key and the public key is stored in ~/.ssh/id_rsa.pub.
  3. Copy the key and add it into your GitHub account,
    cat ~/.ssh/id_rsa.pub
    Go to https://github.com/settings/ssh, click New SSH Key and copy the key over to the account.
  4. Now you should be able to ssh to GitHub,
    ssh git@github.com
    A message like below confirms that the key is enabled,

    Hi learncodingwithher! You’ve successfully authenticated, but GitHub does not provide shell access.
    Connection to github.com closed.

Install Hexo

  1. Install Node.js, which is the JavaScript framework that Hexo depends on. Simply install with Homebrew,
    brew install node
    And this step also installs npm, the Node package manager.
    Confirm Node.js is installed, if this command prints its version number,
    node -v
    npm -v
  2. Install Hexo with npm, (-g for global)
    npm install hexo -g
    Make sure it is sucessfully installed,
    hexo -v

    $ hexo -v
    hexo-cli: 1.0.2
    os: Darwin 16.1.0 darwin x64
    http_parser: 2.5.2
    node: 4.4.4
    v8: 4.5.103.35
    uv: 1.8.0
    zlib: 1.2.8
    ares: 1.10.1-DEV
    icu: 56.1
    modules: 46
    openssl: 1.0.2h

Hexo as a local server

  1. Choose a folder to hold the blog content. There is no need to create it — just let hexo to create and initialize it by this command, (I use my folder path ~/Documents/learnCodingWithHer/ as an example.)
    hexo init ~/Documents/learnCodingWithHer/
    Take a look at what is configured into this folder,

    $ ls -al
    total 656
    drwxr-xr-x@ 12 nancy staff 408 22 Nov 23:16 .
    drwx——+ 26 nancy staff 884 22 Nov 00:14 ..
    -rw-r–r–@ 1 nancy staff 6148 22 Nov 08:30 .DS_Store
    -rw-r–r– 1 nancy staff 65 22 Nov 23:16 .npmignore
    -rw-r–r– 1 nancy staff 1483 22 Nov 23:16 _config.yml
    drwxr-xr-x 12 nancy staff 408 22 Nov 23:17 node_modules
    -rw-r–r– 1 nancy staff 443 22 Nov 23:16 package.json
    drwxr-xr-x 5 nancy staff 170 22 Nov 23:16 scaffolds
    drwxr-xr-x 3 nancy staff 102 22 Nov 23:16 source
    drwxr-xr-x 3 nancy staff 102 22 Nov 23:16 themes

  2. Go to this folder,
    cd ~/Documents/learnCodingWithHer/
    and call npm to install the dependencies that are specified in package.json,
    npm install

  3. Now we can test with the example blog Hexo provides. Use “Hexo generate” command to prepare the static pages for the example blog,
    hexo g
    And the generated data are in a new folder called “public” and a new json file,

    -rw-r–r– 1 nancy staff 23918 22 Nov 23:21 db.json
    drwxr-xr-x 8 nancy staff 272 22 Nov 23:20 public

  4. And then start a local Hexo server
    hexo s

  5. View the blog in your web browser by this link, http://localhost:4000/. The Hexo blog displays. Also this provide a good way to view and check the webpages locally before publishing them to the remote servers, such as GitHub Pages.

Deploy to GitHub

  1. Config the Deployment setting in the blog folder _config.yml,

    # Deployment
    ## Docs: https://hexo.io/docs/deployment.html
    # ssh://git@github.com/learncodingwithher/learncodingwithher.github.io
    deploy:
    type: git
    repo: ssh://git@github.com/learncodingwithher/learncodingwithher.github.io
    branch: master

  2. Install the Hexo Git deployer package.
    cd ~/Documents/learnCodingWithHer/
    npm install hexo-deployer-git --save

  3. Now Hexo is ready to deploy to GitHub Pages! Run this command to deploy the Hexo example blog to GitHub,
    hexo d
    When this message prints, the deployment is complete.

    INFO Deploy done: git

  4. And I can visit it with the link, https://learncodingwithher.github.io/ !

Config the Hexo Blog

A little bit more configs in the _config.yml file — the blog title, subtitle, description and author,

# Site
title: Learn Coding With Her
subtitle: Code to make a better world; learn to be a better coder
description: A tech blog on programming, software and tools
author: Nancy Deng
language:
timezone:

Publish to the Blog

To publish a new post, type this command with the title of the new post,
hexo new "title"
Hexo will create a new markdown file under source/_post/. Use your favourite editor and start to write in Markdown.
After writing is done, generate it with “hexo g“, review with “hexo s“ and deploy it to GitHub with “hexo d“.

Change to Another Hexo Scheme

There are many Hexo schemes published on GitHub. Find one you like and clone it to the blog folder. Apply it by changing the theme setting in the _config.yml file. For example, I use pacman that I find on GitHub.

  1. Clone it to the blog folder and place it under themes/ subfolder,
    cd ~/Documents/learnCodingWithHer/
    git clone https://github.com/A-limon/pacman.git themes/pacman

  2. Modify the Theme setting in the blog folder _config.yml to pacman.

    # Extensions
    ## Plugins: https://hexo.io/plugins/
    ## Themes: https://hexo.io/themes/
    theme: pacman

  3. If hexo g command is called with the previous theme, it is better to remove public/ subfolder first,
    rm -rf ~/Documents/learncodingwithher/public/

  4. Regenerate with the new theme,
    hexo g