Github Pages With Hexo

After around 2 full months of keeping up TIL repository, I’ve FINALLY managed to move on to Github Pages.

There were several thresholds for me before, which were

1. I was not used to Markdowns.
2. I had troubles understanding how Github Pages hosts my blog built on Hexo.

I know these might sound strange, but yeah I guess I didn’t have enough knowledge on how things work on web in terms of build-deploy processes.
So here goes som explanations for those of you who are starting off with Github Pages+Hexo

Github Pages

This is super simple. Just create a repository with the name of [your-username].github.io. After that, just move on with Hexo set up.

Hexo

This is an awesome tool that automatically sets up your Github Pages to work like a blog with Markdown files as postings.

Initial set up comes with simple commands:

// install hexo
npm install hexo-cli -g
// init your blog. 'blog' here is just a name, so you can change it.
hexo init blog
// get into your blog directory
cd blog
// install bundles
npm install
// run your blog on node server, which will run on http://localhost:4000
hexo server

Now when you can confirm it running on localhost, continue with settings.
You can see settings in _config.yml.
You have to change some variables here. Here’s sample for what I customized:

title: Code Jingles
subtitle:
description:
author: Jiwon
language: en
timezone: Asia/Seoul

You also need to set Theme and Deploy, but I’ll get back to it later.

Now go ahead and find some theme that you’d like to use from Hexo’s theme page.
Usually, the themes will provide you sufficient directions to apply it.
For me, I chose Hueman and customized it a bit.
Mostly, it involves git clone command and changing theme in your blog/_config.yml file.

theme: hueman

After that, customize the theme as you like. For me, I even edited some part of style files and layout file so that I can use text instead of image for my logo. I chose one from google font (full of awesome fonts!).
I added my part of customization as custom.styl file, and imported it into style.styl. First time using Styl and it was interesting to try new stuff. Check it out here.

When you are done, most important part now - create a first post!

The command:

hexo new [title]

Please refert to official Docs for full explanation. This command will create new .md file in your blog/source/_posts directory. You just have to write things in that file.

Most important part - how to make this markdown file into a webpage?

These markdowns are not directly taken into your website - it will not look all pretty and nice in markdown format.

You need to convert it into HTML file. But how?
Hexo does it.

Two important commands:

hexo generate
hexo deploy

First command will turn your added files and assets needed for your blog into static files. For example, your markdown file will be turned into html file so that it will look nice and organized for visitors of your blog.
This includes files like css, js.. etc.
The generated files will be saved in blog/public directory.

Please refer here for further understanding in generate command.

You can always check changes to your blog by hexo server command before actually generating the files.

Finally, that you are done with static files, you need to push them to your web server - which is your github repository.

You don’t do this with your usual git push kind of method. Hexo does this for you too. With hexo deploy, it will automatically push the changes into your repository.

But you need to set up deploy methods first in your blog/_config.yml file.
I’ll show you how to set it up with Github, but it supports other services too. Please see here.

cd blog
npm install hexo-deployer-git --save

Then in your _.config.yml,

deploy:
  type: git
  repo: <repository url>
  branch: [branch]      # This is usually 'master' unless you changed branch
  message: [message]    # I excluded this option

If you have set everything correctly, it should deploy your blog to Github Pages automatically and generate the blog.
This may take few moments to actually be observable, so please be patient :)

And that’s it!
It’s simple but could be difficult for those who are not used to web deployment and markdowns. Hopefully this helps for those who’s struggling with Hexo.