Hexo Quick Start

Posted on 2019-01-27 Edited on 2025-10-06 In Hexo

This blog is about how to deploy Hexo with Next theme on your Github pages. It also mentions some common plugins such as search, markdown and Mermaid.

Hisotry

2025-10-05: Upgraded the Hexo version, Next version to latest to fix some weird format errors when running hexo server, now the next theme configuration file is under themes->next->_config.yml, other configuration such as deployment on github is still in main _config.yml file.

Hexo and GitHub Pages

First understand what is GitHub Pages and Hexo.

GitHub Pages is a website for you and your project that hosted directly from your GitHub repository. There is no Database to setup and no server to configure, you even don’t need to know HTML, CSS and other web development toolkits. You just follow the basic git add, commit and push operations and it will automatically build and deploy your blog site for you.

NOTE: If by any reason you recreate the github page site, don’t forget to set up the Pages’s publish branch the same name as it in hexo _config.yml file, for example, I am using published branch.

Hexo is a open source blog framework that transfers plain text files into static website with beautiful theme. You associate it with your GitHub Pages repository, then use Markdown write posts and deploy. Hexo provides basic features for manage the blog site, such as categories, tag, profile, etc. There are a lot of extensions and customizations for Hexo, more details please refer it’s website.

There is a Chinese version explanation, refer this link.

Set up GitHub Pages

Head over to GitHub and create a new repository named username.github.io, where username is your username (or organization name) on GitHub.

If the first part of the repository doesn’t exactly match your username, it won’t work, so make sure to get it right.

Set up Hexo

You need first install Git and Node.js, at the time build this blog I use Node version 10.15.2, download and install it:

CAUTION: Please don’t use latest nodejs! Otherwise the hexo deploy will fail with odd issue, I stick to nodejs v12.22.3, the pkg installer for Max can be downloaded here, or googling the keyword to find desired pkg.

NOTE: To uninstall nodejs completely from Max that installed by pkg, see this reference. After execution, please also remove hexo softlinks from /usr/local/bin if needed.

NOTE: For Mac users, you may encounter some other problems, please refer this link.

Once all requirements are met, install Hexo by running:

1 2	# If upgrade, using the same command. sudo npm install -g hexo-cli

NOTE: For Mac users, you need to enable root user privilege first.

The installation process may generate some warnings even errors, do a sanity check to see if it is good, for example:

hexo -v

hexo-cli: 4.3.0
os: darwin 19.6.0 10.15.7

node: 12.13.1
v8: 7.7.299.13-node.16
uv: 1.33.1
...

Initializing Blog

1
2
3

cd ~/Desktop/
## create a directory called `chengdol.blog`
hexo init chengdol.blog

Go to chengdol.blog:

# boot local hexo server
hexo server

INFO  Start processing
INFO  Hexo is running at http://localhost:4000 . Press Ctrl+C to stop.

If you see this webpage, congratulations! you now have a workable blog with default setting:

Customizing Blog

Let’s open the chengdol.blog directory

The Hexo offical documentation contains lots of configuration setting you can follow, Here I just go through what I have applied.

2021-01-03, 今天添加了一个生成过去规定天数改动或新增博客列表的脚本，这个脚本会自动生成一个置顶的blog，这样就可以随时复习之前一段时间内改动的内容了。

1
2
3

# The flag --local generates localhost link which is used for 'hexo server'
# command. To generate link for deployment, don't use --local.
./review_list_generator.sh [--local]

Backup

有时候需要在不同的电脑上写作(Don’t forget to set Github SSH public key)，这样同步和备份就不太方便。可以仅仅将最重要的文章部分备份下来，也就是source文件夹下的内容，创建一个private git repo即可。在top-level的gitignore file中选择忽略:

1	.source/.git

这样一来就可以在多台电脑上写作并同步了:

1
2
3

# Deploy on github.
hexo clean && hexo g
hexo deploy

Hexo Plugins

https://hexo.io/plugins/

Search

The latest Hexo has native local search support, you just need to enable it in the theme _config.yml file.

Markdown Rendering

The defaul markdown renderer is hexo-renderer-marked, I have migrated it to hexo-renderer-markdown-it for better control and less risk. You need to remove the old renderer and install new one manually, from its README:

# First go to the blog root directory.
# Uninstall old.
npm un hexo-renderer-marked --save
# Install new.
npm i hexo-renderer-markdown-it --save

The configuration is in root _config.yml file:

markdown:
  preset: 'default'
  render:
    html: true
    xhtmlOut: false
    langPrefix: 'language-'
    # To follow the 80 columns wide rule, we need to disable the
    # line break rendering.
    breaks: false
    linkify: true
    typographer: true
    quotes: '“”‘’'

Mermaid Diagram

This Mermaid plugin is for Hexo(not for VSCode), install by running:

1 2	# Go to blog root folder first. npm install --save hexo-filter-mermaid-diagrams

After installation, in Hexo _config.yml file, append:

# mermaid chart
mermaid: ## mermaid url https://github.com/knsv/mermaid
  enable: true  # default true
  version: "7.1.2" # default v7.1.2
  options:  # find more api options from https://github.com/knsv/mermaid/blob/master/src/mermaidAPI.js
    #startOnload: true  // default true

Additionally, appends below snippet at Next theme layout/_partials/footer.swig file.

{% if theme.mermaid.enable %}
  <script src='https://unpkg.com/mermaid@{{ theme.mermaid.version }}/dist/mermaid.min.js'></script>
  <script>
    if (window.mermaid) {
      mermaid.initialize({{ JSON.stringify(theme.mermaid.options) }});
    }
  </script>
{% endif %}

NOTE: the swig file location is subject to change for different Next versions.