「2023.001|EN」Hexo NexT Upgrade Notes

Posted on Edited on Views: Word count in article: 1.3k Reading time ≈ 5 mins.

Reason for Upgrading

My old blog was built with Hexo and NexT theme in 2016, and by 2020 these two projects had undergone huge changes and had many new powerful features, so it was updated once at that time.

Today, 3 years later, it is time to update again. Unlike last time, this time it is actually a re-build rather than an update, because a new github account pwnfan and a new domain name pwn.fan are used.

As for the articles in the old blog, I will move those contents that are still not outdated to the new blog.

About pwn.fan

Pwn is a network term, especially popular in the network security circle, usually meaning "breakthrough and surpass". pwn.fan as a domain name represents a hacker spirit of "enthusiasm for continuous innovation and breakthrough".

What's Different from the Old Blog

  • The new blog uses github action:
    • This way, you only need to push the new blog source code to the source code repo (private), and through the github action already configured in this repo, the static page will be automatically generated and pushed to the directory where the github page is located https://github.com/pwnfan/pwnfan.github.io
    • The old blog needs to manually run the hexo deploy command to deploy.
    • The new blog uses Github Action to deploy static files, so there is no need to add a CNAME file to the project directory. On the other hand, the old blog uses branch deployment and requires adding a CNAME file to the directory.
      • Please refer to Configuring a publishing source for your GitHub Pages site
      • Please refer to Managing a custom domain for your GitHub Pages site
stateDiagram
state "github: blog/main" as s1
state "github: pwnfan.github.io/gh-pages" as s2
state "site: https://pwnfan.github.io" as s3
[*] --> s1: blog update commit
note right of s1: private
s1 --> s2: (through github action hook)\n1. build static pages\n 2. auto commit to
note right of s2: public
s2 --> s3: served by github
  • Multi-language (English, Japanese, Chinese) is enabled, and multi-language articles are planned.
    • As I continue to learn English and Japanese, I have also tried to write English blogs in the past, but writing blogs in multiple languages takes a lot of work, and ensuring high-quality translation will take a lot of time. The emergence of ChatGPT greatly reduces the workload of relatively high-quality translation, so I will try to use 3 languages to publish articles at the same time in the future.
    • If you only want to view articles in one language, you can use the language switch menu at the bottom of the page to switch.

Problems Encountered During Upgrading and Solutions

Custom 404 Page Not Working

Problem

When accessing a non-existent page, the github 404 page is displayed, as shown in the following figure:

Solution

Add permalink: /404.html to the Front-matter of the 404 page:

1
2
3
4
 
---
title: 404
permalink: /404.html
---
KRISTOF ZERBE404 Page in Hexo for GitHub Pages

How to Ignore Certain Pages When Generating Sitemap

Question

When generating sitemap, some pages need to be ignored, such as 404 page. But there is no relevant content in Hexo and Next document.

Solution

After looking through the source code of Hexo, I found out that the sitemap generation function uses the plugin hexo-generator-sitemap, and the README of the plugin explains how to ignore certain pages, just add sitemap: false in the Front-matter of the page:

1
2
3
4
5
 
---
title: lorem ipsum
date: 2020-01-02
sitemap: false
---
hexo-generator-sitemap, READMEExclude Posts/Pages

Multi-language Issue

Please refer to my another article 「2023.002|EN」Issues Series: About Hexo and NexT Theme Multi-Language Support for multi-language issue.

Google Analytics

There is a problem that the setting does not take effect and cannot be counted by Google Analytics.

The reason is that Google Analytics has been upgraded to version 4, and the format of tracking_id has changed to G-XXXXXXXXXX, while the old format is UA-XXXXXXXXX-X, which can be referred to here.

If it is set according to NexT official document as follows:

1
2
3
4
# Google Analytics
google_analytics:
  tracking_id: UA-XXXXXXXX-X
  only_pageview: false

there is no problem.

But if we remove only_pageview or set it to true, it will not support the latest v4 version of tracking_id. Later, I confirmed the related source code, and it was indeed like this. There is currently no specific problem in the NexT official document, and some people have raised related issue.

According to the description in [GA4] Introducing the next generation of Analytics, Google Analytics 4, we can know that Google will stop supporting the old version of Google Analytics on July 1, 2023. This means that websites using the old version of Google Analytics tracking_id such as UA-XXXXXXXXX-X will no longer be able to use it for data statistics. It is recommended that everyone check the relevant configuration discussed above to ensure that their blog functions normally at that time. There are also other ones discussing this issue, which can refer to [Implementation Notes] Hexo Update Google Analytics 4.

Firebase Configuration Issues

The description of the configuration for Firebase in the official document of Next is almost a passing mention, but the actual setting is more complicated and I encountered various problems. Here are the articles I found with solutions, so I won't discuss every specific issues for details:

  • Hexo - Add View Count based on FireBase
  • Application Note #4 - Configure hexo-theme-next
  • 【2021年最新】React×firebaseにて「Uncaught (in promise) FirebaseError: Missing or insufficient permissions.」エラーが出力される原因とその対策
  • 【解決】FirebaseError: Missing or insufficient permissions.
  • https://firebase.google.com/docs/firestore/security/get-started?hl=en&authuser=0#deny-all
  • Structuring Cloud Firestore Security Rules
  • Fix: 'The Cloud Firestore API is not available for Datastore Mode projects.'

Here I will specifically talk about several issues involved.

First, the default mode of Firestore Database is Datastore mode , so information such as article reading statistics cannot be seen in the main interface of Firebase Firestore Database, but is hidden in Google Cloud. Here is the direct link: https://console.cloud.google.com/firestore/databases/-default-/data/panel/.

Second, the writing of Firebase Database role may cause security problems. Here I give the secure writing according to the official document of Firebase, where articles is the name of the collection you created:

1
2
3
4
5
6
7
8
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /articles/{article} {
      allow read, write;
    }
  }
}

Github Action Problem

In the previous section, I mentioned that I used Github Action for CI/CD. To avoid reinventing the wheel, I directly used sma11black / hexo-action, which is a Hexo CI/CD Action for automating deployment.

When using it, I found an error when building: [hexo-renderer-pandoc] pandoc exited with code null.

According to the NexT theme documentation, there are two rendering engines available for mathematical/chemical formulas:

  • MathJax
    • It requires hexo-renderer-pandoc
  • KaTeX

After comparing the two, I chose to use MathJax, set it in the configuration file, and installed hexo-renderer-pandoc locally.

The problem was that the docker image made by sma11black / hexo-action did not install hexo-renderer-pandoc, causing the blog compilation to fail due to the lack of hexo-renderer-pandoc.

I fixed the pandoc issue in my own fork repository pwnfan/blog-github-action.