Hexo Setup General

Posted on In ,

Preface

As a new year resolution, I would like to be better than last year. In the technical aspect, I think starting a blog might be a good way (provided I could keep this habit). I used hexo before, however, due to issues with organizing blog articles and the ugly defaul theme, I stopped after a few articles. After organizing all my browser bookmarks last week, I got some inspirations on how to organize things, hence I am starting a new hexo blog again. Let’s see how far this time I could go.

But firstly, I decided to fix some issues I faced before, to keep my interest and form a habbit of good structure with tags and categories.

Requirements

More could be found on Hexo website:

  • Nodejs
  • Git

Installation

Install Hexo globally with npm on the machine:

1
npm install -g hexo-cli

Setup

Once Hexo is installed, run following commands to initialize Hexo in the target <folder>.

1
2
3
hexo init <folder>
cd <folder>
npm install

Configuration

Note: This section contains my preference (Marked with Personally).

Hexo

Site settings could be modified in _config.yml.

Personally, I feel categories in the permalink can help with better organization.

_config.yml
1
2
3
4
# URL
...
- permalink: :year/:month/:day/:title/
+ permalink: :category/:name/

Difference between :title and :name:

:title is filename relative to source/_posts folder, whereas :name is just filename.

For example, content below at the start of the markdown file with different permalink setting generates different permalink. (Note the extra 2022 for :title setting)

source/_posts/2022/hello-world.md
1
2
title: Hello World
date: 2022-01-21 17:01:34
Setting Result
:year/:month/:day/:title/ 2022/01/21/2022/hello-world/
:year/:month/:day/:name/ 2022/01/21/hello-world/

Post Layout

Personally, I prefer to add updated and categories in the default post layout, this two extra properties can help with better organization. I also like to have a Preface section with a more button to provide a quick summary of the blog post without occupying lots of space by showing the whole article.

./scaffolds/post.md
1
2
3
4
5
6
7
8
9
10
11
---
title: {{ title }}
date: {{ date }}
+ updated:
+ categories:
tags:
---

## Preface

<!-- more -->

Theme

Personally, the default theme is not very aesthetic appealing to me. I decided to change to Next

1
2
3
4
5
cd <hexo_folder>
npm install hexo-theme-next
# optional: remove landscape theme node package and configuration file
npm uninstall hexo-theme-landscape
rm _config.landscape.yml

Change theme to next:

_config.yml
1
2
3
4
5
# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
- theme: landscape
+ theme: next

Customize next theme (Copy theme config file to hexo_folder root directory):

1
2
# copy command for installation with npm
cp node_modules/hexo-theme-next/_config.yml _config.next.yml

My preferred Scheme is Gemini.

1
2
3
4
5
6
7
8
9
10
11
# ---------------------------------------------------------------
# Scheme Settings
# ---------------------------------------------------------------

# Schemes
- scheme: Muse
+ #scheme: Muse
#scheme: Mist
#scheme: Pisces
- #scheme: Gemini
+ scheme: Gemini

Frequently Used Commands

new

1
2
3
hexo new [layout] <title> -p [path_to_article_file]
# short form
hexo n [layout] <title> -p [path_to_article_file]

Creates a new article.

If no layout is specified, default_layout from _config.yml is used. (That is why I changed scaffolds/post.md described in Configuration sections.)

If title contains space inside, surround it with quotation marks.

Personally, I prefer to specify the path to article file when creating a new article, hence I added this -p [path_to_article_file] to the command.

Note:
| path_to_article_file parameter | Actual file path created |
| — | ———– |
| setup | setup.md |
| setup/hexo_1.md | setup/hexo_1.md |
| setup/ | setup/.md |

server

1
2
3
4
5
hexo server
# short form
hexo s
# serving static files
hexo s -s

Starts a local server at http://localhost:4000 by default.

generate

1
2
3
4
5
hexo generate
# short form
hexo g
# deploy after generation
hexo g -d

Generates static files locally.

clean

1
hexo clean

Cleans the cache file (db.json) and generated files (public).

If changing a certain setting does not take effect in the generated static files, running this command and generate static files again could solve the problem. (The favorite restart/reset solves the issue🤣)