Hexo is a powerful tool to set up your own web space with flexibility and control.

Getting Started

Install git if you have not already done so. Enter the command below and it will prompt an installation on Mac:

1
$ git --version

Install nvm (node version manager):

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

Once nvm is installed, restart the Terminal.app and install node.js:

1
$ nvm install stable

Finally, install Hexo with npm (node.js package manager):

1
$ npm install -g hexo-cli

Now you are all set to start creating your first Hexo project.

Initiate Hexo, Create Blog Post On Local Server

First create a root directory for your Hexo project. For me, I created my root directory as a folder called “Hexo” two levels under my home directory (User/username/Documents/Hexo). Initiate Hexo:

1
2
$ cd Documents/Hexo
$ hexo init

Creating your first blog is simple. Run command hexo new <article name> and your first blog post will appear as a markdown file under /source/_post/. Edit the markdown file with Atom (or your favorite text editor).

1
$ hexo new <article name>

You can also create a new webpage in your Hexo project. Run command hexo new page <page name> and a folder with an index.md markdown file will be created under /source/.

1
$ hexo new page <page name>

To view your blog, enter the hexo server command to fire up a local server which displays your website. Enter 0.0.0.0:4000 into your Safari address bar, and your website should be displayed with your first blog post just created above. Note that you can modify your blog post in the markdown file and see instantaneous update on the local server

1
$ hexo server

Deploy Your Blog To GitHub

First create a github repository under www.github.com/<username>/<username>.github.io. Then initiate git under your Hexo project directory.

1
2
$ cd Documents/Hexo
$ git init

Note: At some point, if you accidentally ran git init in your home directory (as oppose to your Hexo project directory). This caused the “git:(master)” to always appear in your terminal prompt and slow things down dramatically. The solution is to execute this command to delete the erroenous Git repository.

1
$ rm -rf ~/.git

Install package hexo-deploy-git:

1
$ npm install hexo-deployer-git --save

Open the _config.yml file under your Hexo directory with Atom. Update the deploy: section as follow:

1
2
3
4
deploy:
type: git
repository: https://github.com/<username>/<username>.github.io
branch: master

Now deploy your new blogpost. Use --watch to monitor progress.

1
2
$ hexo generate --watch
$ hexo deploy

or simply

1
2
$ hexo g
$ hexo d

The command hexo generate generate html files each blog posts from the markdown files, as well as a bunch of other essential files such as blog theme. It then save all these files in the hexo/public directory. The hexo deploy command deploys and pushes the content from the hexo/public directory to the repository (i.e. the master branch, as specified above in the _config.yml file). Now go to http://<username>.github.io to the blog.

Use Your Own Domain Name

We access information online through domain names, like www.something.com. However, Web browsers interact through Internet Protocol (IP) addresses. DNS servers, or Domain Name System servers, translates domain names to IP addresses so browsers can load Internet resources.

The A record maps a name to one or more IP addresses when the IP are known and stable. It is a one-to-many relationship. The CNAME record, or canoical name, maps a name to another name. It should only be used when there are no other records on that name. It is a one-to-one relationship. The ALIAS record maps a name to another name, but can coexist with other records on that name. It is a many-to-one relationship.


Now, we have already set up a website, i.e. <username>.github.io, and we want to map our purchased domain name, e.g. www.something.com to the <username>.github.io site. So every time I enter www.something.com, it shows <username>.github.io on my browser. Hence, what we would like is to create a CNAME record to for our purchased domain name.

To start, we need to first purchased a domain name, and then modify (through domain seller’s web-based interface) the A record to point to each of the following four GitHub servers:

1
2
3
4
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Next, we update the CNAME record of the purchased domain to point to <username>.github.io (through domain seller’s web-based interface).

Note that you can check your DNS records with terminal command dig, or “domain information groper”, which can query DNS servers. You can additional + command to filter on information gathered.

1
$ dig www.something.com

or

1
2
3
$ dig www.something.com +short
$ dig www.something.com MX
$ dig www.something.com +nocmd +nostats +noquestion


Now we create a file called “CNAME”, which containing a single line of your purhased domain name. We store this “CNAME” file in the public folder of your Hexo project directory. This step is important because the hexo depoloy command pushes the content of the public folder (including the CNAME file) to your git repository. This “CNAME” file ensures that the blog is published in your specified purchased domain, as oppose to the domain “https://.github.io”.

1
2
cd Dcouments/hexo/public
echo www.something.com > CNAME

Next, go to _config.yml, and update the following:

1
2
url: http://www.something.com
root: /


Finally we can now generate and deploy Hexo once again. Our blog should now be published and viewable on www.something.com.

1
2
hexo g
hexo d

Setting Shortcuts For Hexo Command

Run these three command to create and load the shell dotfiles: .bash_profile, .bash_prompt and .aliases.

1
2
3
curl -O https://raw.githubusercontent.com/donnemartin/dev-setup/master/.bash_profile
curl -O https://raw.githubusercontent.com/donnemartin/dev-setup/master/.bash_prompt
curl -O https://raw.githubusercontent.com/donnemartin/dev-setup/master/.aliases

Open up the aliases file $ atom ~/.aliases and add shortcuts for your hexo routine.

1
2
3
4
5
alias h="cd Documents/Hexo&&atom ."
alias hs="cd&&cd Documents/Hexo&&hexo g && hexo s"
alias hd="cd&&cd Documents/Hexo&&hexo g && hexo d"
alias hcs="hexo clean&&hexo g&&cd public&&echo 'jackliu234.com' > CNAME&&hexo g && hexo s"
alias hcd="hexo clean&&hexo g&&cd public&&echo 'jackliu234.com' > CNAME&&hexo g && hexo d"