This tutorial is for anyone interested in using “github.io” as their website domain and harnessing the power of Hexo for blogging purposes.
This post assumes that you already have a GitHub account and have git already installed.
I had to go through several different tutorials before I managed to successfully deploy hexo to my website. No one tutorial was perfect for me so here I will share what worked for me. I used Windows 10 and the Git Bash terminal throughout the process. I should have probably used macOS instead but oh well.
If you have some time, it might be useful to first have some knowledge about what you will be working with. Otherwise, skip this part.
Read about GitHub Pages here.
Read about Hexo here.
Read about Node.js here.
Step 1： Make a new GitHub repository
The format of the repo name is as follows:
username.github.io
Note that you should be able to create the repo as long as you do not have an existing repo of the same name. GitHub reserves the domain for your username. Isn't that neat?
Proceed with initializing the repo with a README and click Create repository. Keep in mind the link to your repo.
Step 2: Install Node.js
Download the official Node.js installer here. Take note of the installation path.
Step 3: Install Hexo
Now open your terminal and run the code below. Subsequent codes will all be run on the command line except for Step 5.
1 | npm install -g hexo-cli |
If somehow at this step your terminal states that the command “npm” cannot be found, the solution may be to manually add the path to your system variable (Mine was C:\Program Files\nodejs). Read this on how to change environment variables.
Step 4: Initialize a folder for your website content
In this example, I initialized a folder called “hexo” on my Desktop.
1 | hexo init hexo |
Step 5: Install Git Deployer Plugin
The git deployer plugin is essential to deploy your static files to your website. Run this in your new folder:
1 | npm install hexo-deployer-git --save |
Step 6: Edit hexo/_config.yml to direct hexo to your website
This step is going to enable you to deploy hexo to your website. Open the config file with a text editor and edit the “URL” and “DEPLOYMENT” section as follows:
1 | ... |
You can just copy the link to your new repo and paste it after repo:. Remember, this setting is tailored specifically for GitHub Pages.
Don't forget to save your changes!
Step 7: Deployment test
It is a good idea to first publish the default content to your website and see if it works before you start making changes.
1 | # to view your website locally |
Now, go to username.github.io to see if it works! If it does, congratulations and go ahead and make some changes locally. Note that the result of deployment sometimes takes a while to display. Give it a few minutes before refreshing your website.
Step 8: Making changes
Keep it mind that at this point, the default settings are still in effect; the most obvious one being the theme and posts. The main changes you might want to make are adding a new post, a new page or even changing the theme. In this example, I will show you how to make a new post.
1 | # to add a new post |
By default, the title of your post will be the same as the postname you entered. Locate it under /source/_posts and edit the contents of the post using Markdown! Once satisfied with the changes, go ahead and save them.
Step 9: Post-edit habit
After making some changes, I recommend to always view them locally first. Once you are happy with the changes, generate the static files and then deploy them. To recap:
1 | hexo s |
Have fun blogging with GitHub and Hexo! : )
Crafted on my MacBook Air.