The Ultimate Guide to Building a Blog

After wandering through a very strange learning path, I think I can finally explain how this thing works.

You can start with the official Hexo tutorial.

First, create a GitHub repository.

Its name must be username.github.io.

Then install hexo in the terminal. That is what we are using here.

Mac:

1
brew install hexo

Windows:

1
npm install hexo-cli -g

Then initialize the project:

1
2
3
mkdir username.github.io
hexo init username.github.io
cd username.github.io

After that, connect the local repo to the GitHub repo you just created:

1
2
3
git remote add origin https://github.com/username/username.github.io.git
git branch -M main
git push -u origin main

Those commands are pretty easy to understand once you know a little Git.

The really important line is the url field in config.yml. That field determines how your blog resolves request paths. In other words, it affects where the site thinks its root is, which also affects things like where your images are loaded from.

1
url: https://username.github.io

Yes, really. If you do not believe me, go try some other wrong value and see what happens.

Next, install a theme. I use Butterfly, so I just cloned it:

1
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

Here -b means “clone this branch”, in this case the master branch, into themes/butterfly.

Do not forget to change the theme in the root config.yml:

1
theme: butterfly

Then install a few plugins:

1
npm install hexo-renderer-pug hexo-renderer-stylus --save

Those are the Pug and Stylus renderers. I did not know what they were at first either, but you need them.

1
npm install hexo-deployer-git --save

That one handles deployment.

Everything else is just configuration.

Here are a few common commands:

1
hexo new "title"

Create a new post. You can also create files manually. The short form is hexo n "".

1
hexo generate

Generate the site files, including the public directory. The short form is hexo g.

1
hexo server

Run a local preview server so you can check things before deployment. The short form is hexo s.

1
hexo deploy

Deploy to GitHub. Please do not manually push yourself into disaster like I did. The short form is hexo d.

You can generate and deploy in one go:

1
hexo g -d

If you are not afraid of breaking things, of course. Not like anyone is reading the blog anyway.

I am sleepy. Good night.

Additional notes:

  • Install Git first.
  • Then install npm.
1
curl -qL https://www.npmjs.com/install.sh | sh