木鸟杂记

大规模数据系统

Building a Static Blog With the Hexo Engine

Posted on Edited on In ,

Building a Hexo Blog

One of my New Year’s resolutions is to push myself to write a blog post every week. As a fresh start, cleaning up the house is my usual style. Plus, I felt the Jekyll engine wasn’t very easy to use, so I wanted to switch to a new engine: Hexo. Last year, I noticed more and more blogs starting to use this engine, so I paid attention to it and found it indeed quite good (themes, modes, etc.). I decided to just do it. Thinking that as a CS major, following other people’s tutorials would be too lame, I went straight to the official docs to get started. Of course, pitfalls were inevitable; let’s talk about them below.

Author: Muniao’s Notes https://www.qtmuniao.com, please indicate the source when reposting

Timeline

  1. The day before, I spent about an hour going through the Hexo official docs: https://hexo.io/zh-cn/
  2. I started from scratch and applied for a new GitHub account to experiment with Hexo
  3. I migrated my few previous notes from my old GitHub account to the new one

Reading the Docs

The Hexo docs are written quite clearly, and there is a Chinese version. I skimmed through it. Let me first talk about some basic commands and common configurations you might use, and then briefly discuss my understanding of how Hexo works.

Basic Commands

Going through them roughly in order of use. The Hexo version I used: hexo: 3.8.0, hexo-cli: 1.1.0

  1. Install Node.js, see the overview section of the docs. Mainly the npm command, which is a JS package manager. Static web pages naturally require a lot of JS dependencies.
  2. Install the Hexo CLI: npm install -g hexo-cli
  3. Initialize Hexo: hexo init
  4. Create a new post: hexo new [layout] <filename>
  5. Publish the static site: hexo d (shorthand for hexo deploy)

Basic Configuration

Mainly for GitHub Pages:

The main config file is hexo/_config.yml: basic settings like title, subtitle, etc. are straightforward. What needs attention are deploy and theme.

For Git, if you have your own blog domain, note that you should add a CNAME file (with your domain inside) in hexo/source. At this point, even if you enter qtmuniao.github.io, it will automatically redirect to www.qtmuniao.com.

1
2
3
4
deploy:
  type: git
  repo: <repository url> #https://bitbucket.org/JohnSmith/johnsmith.bitbucket.io
  branch: [branch] #published

hexo deploy -g is a commonly used command for publishing posts. deploy means pushing the files needed to render the blog site (excluding Hexo engine’s miscellaneous files) to a certain branch of the specified repo, and then pointing GitHub Pages to that branch of that repo. -g means that before pushing to the above branch, the generated static files are placed in the public folder.

For themes, there is a post on Zhihu that did a survey of popular Hexo themes. I chose the most popular one, Next, and installed it according to its docs. The version I used is Version 6.0.6.

For the Next theme configuration in themes/next/_config.yml, I mainly chose the Scheme: Gemini and added some Google Analytics info to track website visits.

General Principles

Briefly talking about my understanding of Hexo:

Hexo can be roughly understood as an engine for writing static blogs.

First, let’s talk about “static.” It means there is no server-side backend interaction. You can roughly understand it as there being no database to store all sorts of user info, blog info, and other metadata. With the further development of front-end technologies in recent years, JS can do more and more things. Relying solely on HTML + JS + CSS can already meet the daily needs of writing and cool themes. And it doesn’t require deploying services or renting space, plus GitHub Pages is free, secure, and fast. Therefore, static blogs have become increasingly popular.

Then what is an “engine”? I understand it as taking care of all the things unrelated to writing through simple commands + default configurations, so you only need to focus on writing. Of course, due to the need for personalization, themes and plugins are decoupled and can be customized, published, and shared, thus greatly enriching the playability.

Hexo decouples templates, themes, plugins, and other modules, making blogging easy to get started with yet offering depth to explore.

New Account

My first thought was to directly modify the original repository. After thinking for a moment, I forcibly suppressed this unreliable idea. So I applied for a new GitHub account, and problems followed:

1. Different GitHub accounts cannot add the same SSH key

I Googled around and found a solution.

a. Generate a new SSH key pair (pay attention to the location when generating; I think it’s best to still put it in the ~/.ssh directory, though that depends on personal preference; give it a neat name)

b. Edit the SSH config file, ~/.ssh/config, specifying two host entries and setting them to use different SSH keys.

1
2
3
4
5
6
7
8
9
Host host1
    HostName github.com
    PreferredAuthentications publickey
    IdentityFile ~/.ssh/id_rsa

Host qtmuniao
    HostName github.com
    PreferredAuthentications publickey
    IdentityFile ~/.ssh/qtmuniao_id_rsa

Then you can test the configuration with ssh -T git@qtmuniao.

c. Modify the path in git clone repo.git:

1
2
Before: git@github.com:qtmuniao/qtmuniao.github.io.git
After:  git@qtmuniao:qtmuniao/qtmuniao.github.io.git

Just change the hostname after @ and before : to the configured hostname.

Hexo Experiment

Then I started following my previous idea and directly created a qtmuniao.github.io repository. When running hexo deploy, I encountered the second problem:

2. In the Settings of the qtmuniao.github.io repository, the Source option under GitHub Pages can only be set to master

a. First, let me explain the origin of the problem in detail.

Hexo’s setup is that blog writing and the required Hexo dependencies are maintained in one branch (say, the master branch). Then, when deploying via git, all useful files are push (--force) to a new branch (say, the publish branch). Then in GitHub, you set that branch as the target branch for GitHub Pages.

b. But the redirect solution provided by Hexo didn’t work, namely:

1
2
https://hexo.io/zh-cn/docs/deployment:
Log in to Github/BitBucket/Gitlab, and in the Repository Settings, set the default branch to the branch name configured in _config.yml. Wait a moment, and your site will appear in your Github Pages.

After changing the default branch of qtmuniao.github.io to publish, I opened https://qtmuniao.github.io/ and found it was still pointing to the master branch.

c. So here comes the problem: in the Settings of the qtmuniao.github.io repository, the Source option under GitHub Pages can only be set to master, because it is grayed out.

After some Stack Overflow searching, I roughly figured it out. All your GitHub repositories can have their root directory or a docs folder under the root directory set as the GitHub Pages to be published. But when the username.github.io repository exists, it defaults to setting the master branch of username.github.io as the GitHub Pages to be published, and you cannot change it.

d. Since that’s the case, I created a new blog repository, and then used Hexo to publish the blog code to the gh-pages branch each time. In the Settings of the blog repository, I set the Source option under GitHub Pages to gh-pages, and that was it. The only downside is that the access path includes blog, and the homepage becomes: https://qtmuniao.github.io/blog/. I guess I can fix this by modifying the config later.

e. Later, I dealt with the path issue and found the following hint in hexo/_config.yml: If your site is put in a subdirectory, set url as ‘http://yoursite.com/child’ and root as ‘/child/’. After adding it truthfully, the blog subpath was indeed gone. But when I pointed my own domain to it, I found that various resource files (JS + CSS) could not be fetched. Changing the above config back to url: http://yoursite.com and root as ‘/’ fixed it.

Note Migration

Referring to the Hexo docs https://hexo.io/zh-cn/docs/migration#Jekyll, I didn’t encounter any problems.

Comments Section

To increase interactivity and meet more like-minded people, I wanted to add a comments section. It seems that since the Next version I used is relatively advanced, it supports common comment plugins by default: Gitment, Gitalk.

I chose Gitalk here, since it is a comment plugin developed based on GitHub Issue and Preact. Therefore, you need to first register a GitHub application at https://github.com/settings/applications/new. Note that the Homepage URL and Authorization callback URL should be consistent; if you have a domain configured, just fill in the domain.

After successful registration, obtain the client ID and secret, and enable the following configuration in hexo/themes/next/_config.yml:

1
2
3
4
5
6
7
8
gitalk:
  enable: true
  github_id:   # Github repo owner
  repo:   # Repository name to store issues.
  client_id:  # Github Application Client ID
  client_secret:  # Github Application Client Se
  admin_user:   # GitHub repo owner and collaborators, only these guys can in
  distraction_free_mode: true # Facebook-like distraction free mode

Note that the repo field only needs the Git repo name, not the URL.

Then just redeploy with hexo clean && hexo deploy.

You may encounter a 404 error when logging in; just click to log in to GitHub.

Finally, wish you all have fun.

我是青藤木鸟，一个喜欢摄影、专注大规模数据系统的程序员，欢迎关注我的公众号：“木鸟杂记”，有更多的分布式系统、存储和数据库相关的文章，欢迎关注。 关注公众号后，回复“资料”可以获取我总结一份分布式数据库学习资料。 回复“优惠券”可以获取我的大规模数据系统付费专栏《系统日知录》的八折优惠券。

我们还有相关的分布式系统和数据库的群，可以添加我的微信号：qtmuniao，我拉你入群。加我时记得备注：“分布式系统群”。 另外，如果你不想加群，还有一个分布式系统和数据库的论坛（点这里），欢迎来玩耍。

wx-distributed-system-s.jpg

不妨一读