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.

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/.

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.

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.

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.

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.

I was working on an npm package written in TypeScript. I anticipated that the package would be used by programmers using JavaScript and TypeScript. Using export default works fine in TypeScript. Consuming a default class looks like this:

1
2

import Trello from 'trello-helper'
const trello = new Trello()

The JavaScript users are not so lucky, they need to add a reference to the export named “default.”

1
2

const Trello = require("trello-helper");
const trello = new Trello.default();

This requirement strikes me as very non-intuitive for JavaScript users. Since the savings from using the default export is a pair of curly braces, and we’re all good at typing curly braces, I decided to no longer use export default in my code. That way the JavaScript import becomes the much more familiar:

1
2

const { Trello } = require("trello-helper");
const trello = new Trello();

In his stackoverflow answer to my question around the need for .default, Simon Chan pointed out a nice workaround. As nice as that workaround is, I think I’ll stick with not using export default.