Establish Hexo with GitHub

This is the first time I write my own blog on my own site. I’m inspired by those who use Hexo to establish their own wonderful blog sites. Its flexibility and programmer-friendly paradigm deeply attracts me so that I decide to make a site of my own with Hexo.

Hexo is a static blog framework written by a Taiwanese in NodeJS and then soon adopted by large amounts of people, especially programmers and technical geeks. Even those who have already got used to other blog frameworks like WordPress also migrated to this brand new platform.

This blog is about how to establish a Hexo blog site from scratch on Mac OS X El Capitan. Althogh there’re many similar passages available on the Internet, this one mainly focuses on the difficulties I’ve encountered.

Installation

Install Git (With Administrator Permission and Homebrew)

$ brew install git

Install NodeJS

Select a proper version and download the installation package from NodeJS Official Site

Install Hexo (With Administrator Permission)

$ npm install hexo -g

Start Hexo

Change to any directory where you want to put your blog. Then initiate a blog site with a customized name using

$ hexo init "blog_name"

Now we can see a directory with your specified name right at the current directory. Go into the blog directory and type in

$ hexo server

Hexo server will be started on 0.0.0.0 at port 4000 by default. You can have a look by typing the address in a browser. You can terminate it by typing Ctrl-C in your Terminal.

All Hexo-related configs are stored in _config.yml (If you’re not familiar with yml, you can just regard it as a simplified version of json). The comments there are sufficient for you to understand the usage of each item.

If you’d like to create your own post now, you can type in

$ hexo new "post_name"

Then restart the server as before. Now you can see your new post on your blog site.

If you want to know more about Hexo’s commands (Eg. shorthand of commands), simpliy type in

$ hexo help

in your Terminal. Then help messages will pop out. If this is not enough, you can visit Hexo’s Official Documents for more information.

Link with GitHub

It’s necessary for you to have a GitHub account before you can proceed further. Since it’s simple to get a new account on GitHub, I’ll omit the process and suppose that you now have a GitHub account and its name is xxx.

Create a New GitHub Repository

Login to your GitHub account and create a new repository called xxx.github.io. The notation xxx here refers to your GitHub account name above.

Config Hexo

Edit _config.yml file under your Hexo directory. Find and change corresponding line as below.

deploy:
  type: git
  repository: git@github.com:xxx/xxx.github.io.git
  branch: master

RSA Key Pair Generation

To successfully connect to the GitHub server via SSH, you need an RSA key pair for authorization purpose. It’s quite easy to accomplish on Mac since almost all of modern Macs have already installed tools we need. Open a Terminal and type in below commands.

$ ssh-keygen -t rsa -C "any_comment eg. your email address"

Then all the way hit enter to apply default settings during the key generation process. During this process, you may be asked to set a password to protect your key pair. You can either ignore it by just hitting enter or input a customized password and then hit enter.

If everything works fine, you will find a key pair has been generated under ~/.ssh/ directory. Open id_rsa.pub with an editor and copy the contents in this file.

Login to your GitHub account and under your Account Settings select SSH Keys. Then you just need to enter a customized title for your key and paste what you’ve copied below the title. Done!

To test your connection with GitHub, type in below command in your Terminal.

$ ssh -T git@github.com

If you’ve set a password before, you’ll be asked to enter the password to allow the program to read the protected private key.

If everything is OK, now a connection success message will prompt out.

Deploy Hexo

As long as your connection with GitHub is OK, you can just type in below command within your blog directory to deploy your local site to GitHub every time.

$ hexo deploy

A Deployment done: git information will pop out on your Terminal. To double verify it, you can find that your site has been published at https://xxx.github.io on GitHub Pages tab under your site’s Repository Settings.

Link Your Domain

So far you can reach your own blog site through https://xxx.github.io address. But it’s always better to have your own domain name linked with your blog site so that you can access your site directly via your own domain (I suppose you’ve already had your own domain. If not, please google it first and config your domain. Believe me, it’s quite easy).

To accomplish it, you only need to modify CNAME file under your blog site’s source directory by adding your domain name into this file.

OK! Everything’s in position. Now type your associated domain in your browser’s address field and hit enter. You can see your own blog site right there in front of your eyes.

Congratulations!

Annex

Above are only basic confurations for our Hexo site. If you want to make it elegant and attractive, there is little you can do with only Hexo core module. But fortunately, thanks to its well designed core module, Hexo supports various kinds of plugins and themes to make itself look better and perform better.

Here I want to introduce two plugins and one theme that I’ve used in my own blog.

Theme: Yelee

There’re many themes available on Hexo’s official site. One of which I’m fond of is desinged by a Chinese front-end developer MOxFIVE and it’s called Yelee. Its elegant and modern design have conquered me completely. You can check it here.

Plugin: Hexo-generator-feed

It’s a plugin written in NodeJS to help you generate RSS for your site. Basically it’s convenient to install this plugin with npm install command and config it in your site’s _config.yml file like below.

plugins:
- hexo-generator-feed

feed:
	type: atom
	path: atom.xml
	limit: 20

Most tutorials on the Internet which introduce the installation of Hexo’s RSS tool tell you that that’s all you need to do to generate your site’s RSS feed. But acutally it’s not the case for me. If you deploy your site after above operations, you probably can’t see what you desire. Your feed won’t appear at your_site/atom.xml in this way.

To solve this problem, you need to add your Hexo plugin into your site’s package.json file and put it under dependencies item like this.

"dependencies": {
	"hexo-generator-feed": "^1.0.3"
}

You need to find your plugin’s version manually. Usually it’s the same as its latest version on GitHub if you install it with npm lately.

Besides, the original package.json file is read-only for other users except for its owner. And, of course, you are not its owner by default. So in order to make a change on this file, you may have to change its owner to you first with chown command.

Now regenerate your site and deploy it again, you will find your RSS feed has been generated successfully.

Plugin: Hexo-generator-sitemap

It’s also a NodeJS plugin but aimes to generate a sitemap for you. The installation process is analogous with Hexo’s feed plugin except that it doesn’t need to modify your package.json file but only needs to add it into your site’s _config.yml file like below.

plugins:
- hexo-generator-sitemap

Conclusion

That’s all for what I want to say about Hexo. I’m still new here and I’m continuing my exploration on Hexo. I wish you, who have or haven’t seen this passage, all the best in establishing your own Hexo blog sites and be excited on what you’ve acheived.