Hexo Quick Start
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 underthemes->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 usingpublished
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 nodejsv12.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 | # If upgrade, using the same command. |
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:
1 | hexo -v |
Initializing Blog
1 | cd ~/Desktop/ |
Go to chengdol.blog
:
1 | # boot local hexo server |
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 | # The flag --local generates localhost link which is used for 'hexo server' |
Backup
有时候需要在不同的电脑上写作(Don’t forget to set Github SSH public key),这样同步和备份
就不太方便。可以仅仅将最重要的文章部分备份下来,也就是source
文件夹下的内容,创建一个private
git repo即可。在top-level的gitignore file中选择忽略:
1 | .source/.git |
这样一来就可以在多台电脑上写作并同步了:
1 | # Deploy on github. |
Hexo 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:
1 | # First go to the blog root directory. |
The configuration is in root _config.yml
file:
1 | markdown: |
Mermaid Diagram
This Mermaid plugin is for Hexo(not for VSCode), install by running:
1 | # Go to blog root folder first. |
After installation, in Hexo _config.yml
file, append:
1 | # mermaid chart |
Additionally, appends below snippet at Next
theme layout/_partials/footer.swig
file.
1 | {% if theme.mermaid.enable %} |
NOTE: the swig file location is subject to change for different Next versions.