Here are all the plugins and niche settings that personalize this blog and the Icarus theme.

Remove Uppercase Details

The Uppercase characters overflowed the page and affects the aesthetic.

Find the css tag that contains the keyword Uppercase and remove it.

{page.layout !== 'page' ? <div class="article-meta is-size-7 is-uppercase level is-mobile">

Better Sans Font

In _config.icarus.yml, find the following section providers:

providers:
    # Name or URL template of the JavaScript and/or stylesheet CDN provider
    cdn: jsdelivr
    # Name or URL template of the webfont CDN provider
    fontcdn: https://fonts.googleapis.com/css2?family=Noto+Sans+HK:wght@100..900&display=swap
    # Name or URL of the fontawesome icon font CDN provider
    iconcdn: fontawesome

Choose your favorite font in Google Fonts, and paste the url of the font to fontcdn

Implement the HTML tag <ruby> for Hexo using Tag Plugin feature. Provide auto pronounciation indication for Jyutping (Cantonese), Zhuyin (Taiwanese Mandarin), and Pinyin (Chinese Mandarin), and the default setting for general usage. Support Traditonal and Simplified Chinese characters.

Inspired by the hexo-ruby-character by jamespan.

Install

npm install hexo-zhruby --save

Use cases

Ruby (ルビ) is also known as Furigana (振り仮名). It contains two basic use cases:

1. To clarify or indicate the pronunciation for readers
2. Gikun, in which the characters have different pronunciations than they seem due to convention or for a specific context. For example, the pronunciation of 煙草 in Japanese is tabako (tobacco).

Usage

TLDR: Usage: {% tag rb|rt %}; Tag options: ruby_def, ruby_jy, ruby_py, ruby_zy.

---

Disclaimer: For explaination on Tag Plugin and Scripts in Hexo, you may take a look of this post.

Plugin

Be Careful! Don’t mix Plugin, Tag, and Tag Plugin in Hexo, even though they look extremely similar.

Usually, Plugin are for complicated functions. Yet if you want to publish your custom Tag Plugin to the NPM registry or even shown on the Hexo Community Page, Plugin would be a very good choice.

From Script to Plugin

Assume you already have a script call index.js, and you want to turn it into package, you may do the following:

1. Navigate node_modules folder in your project folder. This is the folder where Hexo stored all the packages for your blog. Create a folder inside and the name must begin with hexo- or Hexo will ignore it.

2. Your folder must contain at least two files: the actual JavaScript code and package.json file that describes the purpose of the plugin and sets its dependencies.

   .
   ├── index.js
   └── package.json
   

3. In package.json, it should at least have the name, version and main entries set.

   {
       "name": "hexo-my-plugin",
       "version": "0.0.1",
       "main": "index"
   }
   

4. In the root package.json of your hexo project, you also need to list your plugin as a dependency, for Hexo to detect and load it.
   Please remember that if your package contain other dependencies, also install and list them for testing and dubugging.

   {
       "name": "hexo-site",
       "version": "0.0.0",
       "private": true,
       "scripts": {
           "build": "hexo generate",
           "clean": "hexo clean",
           "deploy": "hexo deploy",
           "server": "hexo server"
       },
       "hexo": {
           "version": ""
       },
       "dependencies": {
           "hexo": "^7.3.0",
           ...
           "hexo-my-plugin": "0.0.1",
           "my-plugin-dependency1": "2.0.0",
           "my-plugin-dependency2": "2.0.0"
       }
   }
   

If you run command that check all the package after step 4, for exmaple hexo clean, it will check all the packages in node_modules and remove packages that are not publish on npm.

Publish Plugin to npm

To publish your package on the NPM registry, don’t forget you have to setup your account on npm first.

To color your personal Hexo Blog with more features, scripts and plugins are your powerful tools to use. Below we are trying to create our own tag plugin for the Hexo blog.

Tag Plugin

Be careful! Tag plugins are different from post tags.

Tag plugins are special type of syntax that you may use in your Markdown file.

Hexo has already provided some default Tag plugins like Block Quote and iframe.

Usage

For example, the syntax of iframe tag is:

{% iframe url [width] [height] %}

Let say I want to embed a video from me and my friends’ YouTube video:

{% iframe https://www.youtube.com/embed/XIOl6BU7s9I?si=yTYsHIXNM6o-Zl9Z 820 461%}

Methods to Deploy Hexo to GitHub.io

Assume you’ve created a repository on GitHub called <username>.github.io. Here are two common method you can deploy you Hexo Blog:

Hexo Command

Hexo’s documentations and Tutorial has provided sufficient instructions on deploying your personal website on your GitHub repository.

According to the Hexo Tutorial, we can deploy the repository by using GitHub Actions.

1. Create and Add the following contents to .github/workflows/pages.yml:

   name: Pages
   
   on:
   push:
       branches:
       - main # default branch
   
   jobs:
   build:
       runs-on: ubuntu-latest
       steps:
       - uses: actions/checkout@v4
           with:
           token: ${{ secrets.GITHUB_TOKEN }}
           submodules: recursive
       - name: Use Node.js 20
           uses: actions/setup-node@v4
           with:
           # Examples: 20, 18.19, >=16.20.2, lts/Iron, lts/Hydrogen, *, latest, current, node
           # Ref: https://github.com/actions/setup-node#supported-version-syntax
           node-version: ">=20" 
   
       - name: Cache NPM dependencies
           uses: actions/cache@v4
           with:
           path: node_modules
           key: ${{ runner.OS }}-npm-cache
           restore-keys: |
               ${{ runner.OS }}-npm-cache
       - name: Install Dependencies
           run: npm install
       - name: Build
           run: npm run build
       - name: Upload Pages artifact
           uses: actions/upload-pages-artifact@v3
           with:
           path: ./public
   deploy:
       needs: build
       permissions:
       pages: write
       id-token: write
       environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
       runs-on: ubuntu-latest
       steps:
       - name: Deploy to GitHub Pages
           id: deployment
           uses: actions/deploy-pages@v4
   

2. Install hexo-deployer-git.

3. Add/Change the following configurations to _config.yml:

   deploy:
   type: git
   repo: https://github.com/<username>/<project>
   # for example, this blog is https://github.com/greenmeeple/greenmeeple.github.io
   branch: gh-pages
   

4. After finishing your bog posts, Run hexo clean && hexo deploy.

GitHub Desktop

Many Users installed GitHub Desktop for better visualization on changes, so do I. It provides more intuitive push and commit procedure and instruction compared to terminal. Most of the time I use it to make sure no unexpected line changes or modification.

But soon I noticed that, every time after running hexo clean && hexo deploy, GitHub Desktop will warn me that there’s something need to be pulled. When I pull it for merging it return Unable to merge unrelated histories in repository. Even in the image above, it shows that I should pull something. However, how would I need to pull if I’ve just push it?

Prime superscript problem (e.g. x’_i) in Mathjax

When I was using Mathjax to create math formula in my blog post, I typed
((q_1, q_2), a, (q'_1, q'_2)) \in S \times \Sigma_{int} \times S and it rendered as

$((q_1, q_2), a, (q’_1, q’2)) \in S \times \Sigma{int} \times S$

However, when ((q_1, q_2), a, (q'_1, q'_2)) & \in S \times \Sigma_{int} \times S are seperated, they rendered properly.

$$((q_1, q_2), a, (q’_1, q’_2))$$

$$\in S \times \Sigma_{int} \times S$$

Maybe I should use \left and \right for (), just like \lbrace and \rbrace for {}?

So I typed \left( \left( q_1, q_2 \right), a, \left( q'_1, q'_2 \right) \right) \in S \times \Sigma_{int} \times S, didn’t work out:

$\left( \left( q_1, q_2 \right), a, \left( q’_1, q’2 \right) \right) \in S \times \Sigma{int} \times S$

Source of error