Blogging with Hexo and GitHub Pages

I just started using Hexo for this blog, and I had a little trouble getting started. Mostly my normal node.js coding process got in the way. I created a folder for the project, did a git init and started on the process. That was a mistake. It turns out an important “step” is not to do anything with git. You do need to create a new repo in GitHub pages and name it [username].github.io where you replace [username] with your GitHub username (i.e., for me rolias.github.io). Your repo needs this exact naming convention. Don’t create a readme, don’t do anything else with GitHub or git, let Hexo handle everything else.

Step by Step

1. Install Hexo globally

I know you hate to install things globally. Do it anyway.
npm install -g hexo-cli
You can verify it installed by checking the version
hexo -v
If you don’t get a response with version information, it didn’t install correctly.

2. Create the project

Go to a folder where you want to store the entire project and enter
hexo init [username].github.io
Remember here and in all the following steps to replace [username] with your actual username as talked about in the introductory paragraph (I won’t tell you again, I promise).

3. Fire it up

Move into the newly created folder and then do an npm install.

1
2
cd [username].github.io
npm install

4. Configure the project title, author and timezone

Use your favorite code editor and edit the _config.yml file. I prefer VS Code so at this point in the terminal I type code . and that loads the project. Near the top, you’ll see the #Site section. Put in the title for your blog, the subtitle (if you use one), and put your name in the author: entry.

Warning - If you don’t leave a space after the : for each entry the generator will complain.

In the timezone, you need to put a moment compatible timezone. Using their site click on the map to get the string needed for your timezone. For example, here on the west coast of the U.S., I use America/Los Angeles.

A little lower you’ll see the # URL section. Enter your information for the url: entry. http://[username].github.io/.

VSCode Tip - I love the built-in terminal window View→Terminal (⌃`). I like it so much I use two of them by using either the split terminal icon or the ⌘\ shortcut. Having two windows helps because we’re going to dedicate one terminal to run the server, but we want to issue Hexo terminal commands in the other pane.

5. Start the test server

In the terminal type hexo server - This isn’t completely necessary, but the odds are good you want to check out on your local server how your post looks before you deploy it up into GitHub. I like to use the right terminal pane in VSCode for this.

Remember - any time you modify the _config.yml file, stop the server with ⌃c and restart it to pick up the changes.

6. Test the site

Open a browser and type in the address bar localhost:4000. Your new site will load and show you the default home page. After the next step, you can feel free to delete the sample default post.

7. Create a New Post

In the terminal type

1
hexo new 'Your blog post title'

You’ll get some feedback about the file created in source→_posts. The file will contain the header with the title and date. You can now open that file in your editor and write your post.

Tip - You’ll probably want to add some tags here. This is also another place to make sure you leave space after the : for each entry.

Go back to your browser and hit refresh. My experience is that Hexo will automatically generate the new content on demand. There is also a hexo generate —watch command you can read about in the hexo docs. When your post is ready for the world, go to the next step.

8. Clean and Deploy

You don’t have anything to clean yet, but it’s a good habit to do both every time. Type two commands

1
2
hexo clean
hexo deploy

Go back to your browser and enter https://[username].github.io . Your blog site is live and running in GitHub pages. Well almost. It can take a couple of minutes before GitHub catches up and pushes your changes live. Another reason to use a test server.

Script Tip - You can edit your package.json and add a script that will do both the clean and deploy steps. Add this section

1
2
3
"scripts": {
  "deploy": "hexo clean; hexo deploy"
},


Now from the terminal you can type npm run deploy to deploy your changes to GitHub.

9. Storing the Hexo Site in GitHub

That’s a blog for another day, and that day has arrived.

References and Shout Outs

This gist from btfak - which has a more laconic version of many of these steps.
Jeff Ferrari post on taking advantage of the GitHub docs folder to publish posts instead of using your username.github.io page.