Creating Hexo Blog

Do you like this page? And do you want to create such a page by yourself?
Don’t worry, it’s really pretty simple. You don’t even have to have any special programming skills, only some basic JS understanding, markdown knowledge and a bit of time.

What is Hexo?

A fast, simple & powerful blog framework

That’s what they say on their website, and after having 2 pages deployed with Hexo, I can definately confirm.
Basically, Hexo is a complete webpage generator built on top of NodeJS. It translates markdown documents into HTML and generates static files. So no, you can’t really create nice dynamic pages with hexo. But for stuff like blogs, personal portfolios or just web presentations, it is perfect. Hexo uses PugJS templating engine, which allows users to create their own themes pretty fast. Most of them are available on Hexo’s official Themes page.

Getting Started

Installing NodeJS and npm

First of all, you will need NodeJS and NPM installed. This process differs from different OS types, so I will list only Windows and Linux (Ubuntu/Debian based).
Head over to nodejs.org and download the latest version of Node (13.9 at the time of writing). Install the executable and you’re done.
On Linux, things are a bit different. Best way you can do this is by using NVM (Node Version Manager), which can be downloaded by running

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash

after that, you can install Node by simply typing

nvm use 13

and it will automatically download and setup everything.

If everything went correctly, we should have installed both NodeJS and NPM. We can check by running

node -v
npm -v

and it should return current version.

Installing Hexo

Next, we need to create a new folder in which we’ll setup our Hexo blog. Then, open terminal in that folder and type

npm install hexo hexo-cli -g

You maybe have to run this as a sudo since we’re using the -g flag (which means install globally), but that depends on your distro and config.

When everything is done, simply run

hexo init

Understanding folder structure

As with most of Node frameworks, we have some folder structure we need to understand. It should look something like this

.
├── _config.yml
├── package.json
├── scaffolds
├── source
|   ├── _drafts
|   └── _posts
└── themes

_config.yml

In this file, you’ll find.. well, configuration options of your blog. You can define stuff such as website title, directories, post naming and URL scheme, pagination and theme. Feel free to explore this file, it is pretty well commented and everything is named as simple as possible.

package.json

This file is for node, and we won’t be using it in this project. It contains information about dependencies,

scaffolds

This is basically template for our pages and posts. You can define them here, and everytime you create a new page or post, it will use this scaffold. So if you want to have some sort of prologue, header or whatever in every post, you can define it in here.

source

In this folder, your page content will be stored. It ignores hidden folders and files/folders prefixed with “_”, except _posts folder. All files that can be rendered will be put into public folder.

themes

Here, you will install your themes.

Using Hexo

Creating your first post

So now we understand what is going on, we can create our first blog post. We do this by simply running

hexo new [layout] <title>

where layout is one of defined scaffolds and title is, well, your post title. There are 3 pre-defined layouts: post, page and draft. Drafts won’t be processed and rendered until they’re marked as either page or post widh publish command.
So now we created new post, we can edit it. I recommend any good markdown editor, I personally prefer (Typora)[https://typora.io/], or you can just use any text editor. Also, using Atom or VS Code with .md editor is not bad. Now, you can write whatever you want!

Creating scaffolds

By now you probably created at least one page, and noticed that everytime you create a new file, there is already some text in it. Probably looked something like:

---
title: {{ title }}
date: {{ date }}
tags:
---

This is front-matter that won’t be displayed on your page, but Hexo can figure out some stuff from it, such is the date for example. You can also add tags and categories to then be able to find and categorize your posts. What you can define there can be found (here)[https://hexo.io/docs/front-matter].
So you can now edit and/or create new scaffolds as you wish.

Customizing Hexo with themes

Now, the default theme doesn’t look that bad. But I’m sure you can find something mroe to your taste on (themes page)[https://hexo.io/themes/]. Most of themes have Chinese documentation or are in Chinese, but they should also work for English sites. You can install them with instructions that are written on their GitHub pages, or most of them (if hosted on git) can be installed by

git clone https://github.com/<USERNAME>/<GITREPO>.git themes/<THEME-NAME>

obviously replacing placeholders. Then in _config.yml file, you need to define theme you’re using by setting

theme: landscape

to theme name. For example, I’m using theme called next, so I have

theme: next

Each theme have it’s own _config.yml file in their folder, where you can define some extra stuff. Since this differs extremely from theme to theme, I won’t be describing it in depth. It should be commented and if not, try to contact the theme author.

Using plugins

Hexo also have support for different plugins, which can be downloaded from plugins page. You install them using NPM, again, installation guide should be present on its github page. If not, contact author. This also differs from plugin to plugin, it either gives you more run flags, new config elements or just completely new features, so the best thing you can do is read the documentation and move from that.

Deploying

When you’re done writing, you obviously want to see what you made. You can do this by running

hexo server

which by default runs on http://localhost:4000/. Important note, this is NOT how you deploy your server to the world. This is just for previewing files, correcting and seeing if you like theme or plugin works.

Generate static files

If you want to publish your site to the internet, you need to generate static files, since Hexo is a website generator. You can do this by simply running

hexo generate

which will generate all the files necessary to /public folder. Now you can serve your files using Apache or Nginx or whatever server you prefer. You can also specify the route where files will be generated, so you don’t have to copy them everytime to you host folder. For example, Apache uses /var/www/html/, so you can set

public_dir: /var/www/html/

in _config.yml.

Deploy your blog to —

You can deploy your server to multiple services, for example GitHub pages. This official tutorial will guide you throught this process. I use Netlify for my site, which watches my GitHub repository for changes and automatically fetches them and restarts my page, so everything I have to do after writing a post is to git push and I’m done.

Conclusion

By now, you should have your first blog created and hosted somewhere on the internet. If you’re not sure by something, try to consultate the docs or Google, there are many posts like this about creating blog using Hexo.
As you can see, creating webpage with Hexo is really simple, painfull and you don’t really need any programming knowledge. I hope you enjoyed this basic tutorial.