Jocodoma

Joco's Tech Blog

0%

Setup Blog using Hexo on GitHub

Posted on In , Disqus:
Symbols count in article: 6.5k Reading time ≈ 6 mins.

I was looking for an easy way to setup a personal blog for free but meanwhile also learning something new. It came out that setting up a website using Static Site Generators and GitHub Pages is kind of interesting and fulfill my needs. So, today I am going to briefly describe how I setup my blog using Hexo on GitHub page.

References:
StaticGen: https://www.staticgen.com
Hexo: https://hexo.io
Hexo Docs: https://hexo.io/docs/
NexT theme: https://github.com/theme-next/hexo-theme-next
Introduction | Hexo - Static Site Generator | Tutorial

Requirements

My Environment

Setup Node.js

  • Install Node Version Manager (NVM)
    The way I installed Node.js on MacBook is to use Node Version Manager (NVM).

    1
    curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash

    To verify that nvm has been installed, do:

    1
    command -v nvm

  • Install Node.js and NPM

    1
    2
    nvm install --lts=carbon
    nvm install-latest-npm

References:

GitHub Page

It should be fairly easy to setup your GitHub Pages by following their instructions.

In my case, I have my GitHub Pages and Hexo source files in different repositories as follow. Generated Hexo static files will be deployed directly on GitHub Pages.

So, if you follow my setup, you should have at least two repos ready, one for GitHub Pages and one for Hexo files.

Hexo

Setup Hexo

Install Hexo

1
npm install -g hexo-cli

Setup Hexo and Your Site

1
2
3
4
cd <YOUR_WORKSPACE>
hexo init <YOUR_HEXO_SITE>
cd <YOUR_HEXO_SITE>
npm install

Setup Git

After Hexo site is initialized locally, let’s setup the git for the Hexo site. In my case, the URL of Hexo repo is https://github.com/jocodoma/blog.git.

1
2
3
4
5
6
7
8
cd <YOUR_HEXO_SITE>
git init
git remote add origin https://github.com/jocodoma/blog.git
git remote -v update -p
git pull origin master --rebase
git add .
git commit -m "initial hexo commit"
git push -u origin master

Setup NexT Theme

Here we will checkout the latest version (v6.4.2 as of 2018/10/13) of NexT theme as a git sub module.

1
2
3
4
5
cd <YOUR_HEXO_SITE>
git submodule add https://github.com/theme-next/hexo-theme-next themes/next
cd themes/next/
git checkout tags/v6.4.2
cd ../../

To update NexT theme, please see Update NexT Theme.

After installed NexT, you may add NexT options in site’s _config.yml.

References:

Modify Config File

You can find my full Hexo config settings with NexT options here. Below is just an example:

_config.yml
1
2
3
4
5
6
title: Jocodoma
author: Joseph Chen
timezone: America/Los_Angeles
url: https://jocodoma.github.io/blog
root: /blog/
theme: next

Reference:
Hexo doc - Configuration: https://hexo.io/docs/configuration.html

Hexo Server

You can start a Hexo server on local machine to review your changes before publishing to the server.

1
2
cd <YOUR_HEXO_SITE>
hexo server

By default, your website will run at http://localhost:4000. The -p option can be used to set a different port.

1
hexo server -p 5432

Setup Hexo Deployment

Hexo provides a fast and easy deployment strategy. You only need one single command to deploy your site to your servers. Before that, let’s install hexo-deployer-git first.

1
2
3
cd <YOUR_HEXO_SITE>
npm install hexo-deployer-git --save

Deployment on GitHub Pages Directly

Update the hexo config file for deployment.

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

Add the deployed repo as a Git sub module to .deploy_git folder to keep the commit history.

1
git submodule add -f -b master git@github.com:jocodoma/jocodoma.github.io.git .deploy_git

Remove .deploy_git folder will reset the repo, which means your commit history will be gone.

For more info, please see: https://github.com/hexojs/hexo-deployer-git

Reference:
Hexo doc - Deployment by Git: https://hexo.io/docs/deployment.html#Git

Deployment on html(gh-pages) Branch

This method is specifically for the case where the sub URL of the site is used. In this case, we need an additional branch from Hexo blog repo, called html branch.

Update the hexo config file for deployment.

_config.yml
1
2
3
4
deploy:
  type: git
  repo: https://github.com/jocodoma/blog.git
  branch: html

Make sure that you have an orphan branch (html branch) ready for deployment.

1
2
3
4
git checkout --orphan html            # create an orphan branch named html
git rm -rf --cached $(git ls-files)   # unstage all files
# Remove all files
# Create a dummy file and check-in to the orphan branch

Below are the commands to generate and deploy your site:

1
2
3
hexo clean      # Hexo clean the folder firstCleans the cache file (db.json) and generated files (public).
hexo generate   # Generates static files in the "public" folder.
hexo deploy     # Deploys your website.

The last two commands can be combined as following:

1
hexo deploy -g

After you are done with deployment, the generated static files should be in html branch of blog (Hexo files) repo.

For more advanced settings, please see Hexo doc - Commands.

Add Submodule to GitHub Pages (for html branch approach)

Setup git submodule in your GitHub page working tree. In my case, it’s like following:

1
2
cd jocodoma.github.io/
git submodule add -f -b html https://github.com/jocodoma/blog.git blog

To update git-submodule, do:

1
2
cd jocodoma.github.io/
git submodule update --remote --merge blog/

The final step is to make sure you commit the code and push back to remote repo. Now, you should be able to see your Hexo blog on your GitHub page, which in my case is https://jocodoma.github.io/blog/. Yay!!

Plugins

Update

Update NVM

In case if you need to upgrade your NVM, you can do:

1
2
3
4
cd "$NVM_DIR"
git fetch --tags origin
git checkout `git describe --abbrev=0 --tags --match "v[0-9]*" $(git rev-list --tags --max-count=1)`
. "$NVM_DIR/nvm.sh"

References:

Update node

1
2
3
4
5
nvm ls  # check the installed version
nvm ls-remote --lts  # check available versions on remote server
nvm install --lts=carbon  # node v8.11.3
nvm uninstall OLD_VERSION  # optional
nvm install-latest-npm

Update Hexo

1
2
cd <YOUR_HEXO_SITE>
npm update

Update NexT Theme

  1. List all available updates:
    1
    2
    3
    cd <YOUR_HEXO_SITE>/themes/next/
    git fetch
    git log --no-walk --pretty="%h %d %s" --tags --abbrev-commit --decorate=full
  2. Select the version you want to update:
    1
    git checkout tags/v6.x.x
    Here’s my script to check and update NexT theme.