计软杂谈hexo

As a fan of the Touhou Project, I have created hexo-theme-reimu, a Hakurei Reimu-themed Hexo theme. It combines elements from the landscape, Tangyuxian, and Shoka themes.

Github Repository: (If you find it useful, please give it a star. Thank you!)

Github
Github
https://github.com/D-Sketon/hexo-theme-reimu

Demo:

hexo-theme-reimu Content Display
hexo-theme-reimu Content Display
hexo-theme-reimu Content Display

Development Log:

hexo-theme-reimu Development Log
hexo-theme-reimu Development Log
If you have any questions or suggestions, feel free to submit an [Issue](https://github.com/D-Sketon/hexo-theme-reimu/issues). ## 1.6.0 **2025.03.16** ### Features - Added `pangu` configuration

astro-theme-reimu Demo: Demo Website
hugo-theme-reimu Demo: Demo Website

Features

Basic Features

  • ✨ Complete blog functionality
  • 🔄 Compatible with Hexo 6 and above
  • 📱 Responsive layout
  • 🌙 Dark mode support
  • 🅰️ i18n support

Code & Math

  • 🖥️ Code highlighting & copying
  • ➗ KaTeX / MathJax3 math formula support
  • 📊 Mermaid flowchart support

Search & Comments

  • 🔍 Algolia search integration
  • 🔍 Local search integration
  • 💬 Multiple comment system support:
    • Valine
    • Waline
    • Twikoo
    • Gitalk
    • Giscus

Statistics & Analysis

  • 📊 Article read statistics (Valine / Waline)
  • 👥 Visitor statistics (Busuanzi)

Media & Interactive Features

  • 🎵 Music player support:
    • Aplayer
    • Meting
  • 🖼️ Image lazy loading
  • ⚡ Loading animations
  • 🖱️ Mouse effects:
    • Animation effects
    • Reimu mouse pointer
  • 👾 Live2D / Live2D-widgets integration
  • 📑 Table of contents (TOC)
  • 🔄 PJAX support
  • 🔧 ServiceWorker implementation
  • 📰 RSS subscription

Design & Customization

  • 🎨 Icon support:
    • Iconfont
    • FontAwesome
  • 🔗 Built-in tag plugins:
    • Internal links
    • External links
    • Friend links
  • 🎨 Custom Containers
  • ©️ Article copyright notice
  • 🌐 Custom CDN source configuration
  • 🎨 Share card functionality

Installation

Beginners can directly use reimu-template. It comes pre-installed with hexo, hexo-theme-reimu, and other functional packages. Just clone the repository, install dependencies, and modify the configuration to get a basic blog!
It already includes the following packages, and you only need to configure them:

  • KaTeX / MathJax3 (@reimujs/hexo-renderer-markdown-it-plus)
  • mermaid (hexo-filter-mermaid-diagrams)
  • git deploy (hexo-deployer-git)
  • rss (hexo-generator-feed)

Using npm

1
npm install hexo-theme-reimu --save

Or clone the repository directly into the /themes folder and rename it to reimu

1
git clone https://github.com/D-Sketon/hexo-theme-reimu.git

Then modify the theme in _config.yml

1
theme: reimu

Usage

Basic Structure

To ensure correct display, please refer to _example and create _data, about, and friend folders in the source directory (Note: This is the source folder in the blog root directory, not the source folder in the theme!)

_data

  • Store the author’s avatar in the avatar folder, default name avatar.webp, which can be configured in the inner _config.yml as follows:
1
avatar: "avatar.webp"
  • Store article covers in the covers folder
  • Store article cover URLs in covers.yml

about

index.md serves as the About page

friend

index.md serves as the Friends page. Fill in the friend link information in _data.yml to display the corresponding friend cards on the page.

Cover, Banner & Favicon

Cover

The cover display logic is as follows:

  • If the article’s Front matter contains a cover URL, both the article banner and the homepage thumbnail will display this URL.
1
2
3
4
---
title: Hello World
cover: https://example.com
---
  • If the article’s Front matter contains cover: false, the article will not display a banner (the homepage will still show a random image).
1
2
3
4
---
title: Hello World
cover: false
---
  • If the article’s Front matter contains cover: rgb(xxx,xxx,xxx), the article banner will be a gradient solid color (the homepage will still show a random image).
1
2
3
4
---
title: Hello World
cover: rgb(255,117,117)
---
  • Otherwise, search the covers folder and covers.yml, and randomly select an image from them.
  • If none of the above files exist, the banner will be displayed.

The banner is stored in themes/reimu/source/images/banner.webp and can be modified in the inner _config.yml.

1
banner: "/images/banner.webp"

Favicon

The favicon is stored in themes/reimu/source/images/favicon.ico and can be modified in the inner _config.yml.

1
favicon: "/images/favicon.ico"

Sticky Posts

Add sticky: true to the article’s Front-matter.

1
2
3
4
---
title: Hello World
sticky: true
---

Code Blocks

To ensure correct display of code blocks, please make sure the outer _config.yml has the following configuration:

(<7.0.0)

1
2
3
4
5
6
highlight:
  enable: true
  wrap: true
  hljs: false
prismjs:
  enable: false

(>=7.0.0)

1
2
3
4
syntax_highlighter: highlight.js
highlight:
  wrap: true
  hljs: false

Code blocks also provide a copy function. Click the copy button in the upper right corner of the code block to copy the code. The copy function can be configured in the inner _config.yml.
success is the prompt when copying is successful, and fail is the prompt when copying fails. Additionally, you can configure a copyright notice. When the number of copied characters exceeds count, the content copyright notice will be added after the copied content.

1
2
3
4
5
6
7
clipboard:
  success: Copy successful (*^▽^*)
  fail: Copy failed (ﾟ⊿ﾟ)ﾂ
  copyright:
    enable: false
    count: 50 # Add copyright notice when the number of characters exceeds this value
    content: Copyright: All articles in this blog, unless otherwise stated, are licensed under BY-NC-SA. Please indicate the source when reprinting!

v1.1.0 added a configuration to control the default expansion state of code blocks. expand can be set to true, false, or a number. A number indicates that the code block will be collapsed by default when the number of lines exceeds this number.

1
2
code_block:
  expand: true # true | false | number

In-site Comments

In-site comments can be controlled independently for each article using the comments in the Front matter.
When comments is false, comments will not be displayed. When comments is true or not specified, the display of comments will be determined by the configuration in _config_yml.

If using Valine
Please refer to the official documentation to complete the LeanCloud configuration, and in the inner _config_yml, set valine.enable to true and fill in your appId and appKey.

1
2
3
4
valine:
  enable: true
  appId: "your appId"
  appKey: "your appKey"

If using Waline
Please refer to the official documentation to complete the LeanCloud configuration, and in the inner _config_yml, set waline.enable to true and fill in your serverURL.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
waline:
  enable: true
  serverURL: "your server url"
  lang: zh-CN
  locale: {} # https://waline.js.org/guide/features/i18n.html#%E8%87%AA%E5%AE%9A%E4%B9%89%E8%AF%AD%E8%A8%80
  emoji:
    - https://unpkg.com/@waline/emojis@1.2.0/weibo
    - https://unpkg.com/@waline/emojis@1.2.0/alus
    - https://unpkg.com/@waline/emojis@1.2.0/bilibili
    - https://unpkg.com/@waline/emojis@1.2.0/qq
    - https://unpkg.com/@waline/emojis@1.2.0/tieba
    - https://unpkg.com/@waline/emojis@1.2.0/tw-emoji
  meta:
    - nick
    - mail
    - link
  requiredMeta:
    - nick
    - mail
  wordLimit: 0
  pageSize: 10
  pageview: true

If using twikoo
Please refer to the official documentation to complete the Tencent Cloud or Vercel deployment, and in the inner _config_yml, set twikoo.enable to true and fill in your envId.

1
2
3
4
twikoo:
  enable: true
  envId: # For Tencent Cloud environment, fill in envId; for Vercel environment, fill in the address (https://xxx.vercel.app)
  region:

If using giscus
Please refer to the documentation to complete the repository configuration, and in the inner _config_yml, set giscus.enable to true and fill in the corresponding data.

1
2
3
4
5
6
7
8
9
10
11
12
giscus:
  enable: true
  repo: "your repo"
  repoId: "your repoId"
  category: "your category"
  categoryId: "your categoryId"
  mapping: mapping
  strict: 0
  reactionsEnabled: 1
  emitMetadata: 0
  inputPosition: bottom
  lang: zh-CN

If using gitalk
Please refer to the official documentation to complete the repository configuration, and in the inner _config_yml, set gitalk.enable to true and fill in the corresponding data.

1
2
3
4
5
6
7
8
gitalk:
  enable: true
  clientID: "your application client ID"
  clientSecret: "your application client secret"
  repo: "your repo"
  owner: "repo owner"
  admin: "repo owner and collaborators"
  md5: false # Whether to use md5 to encrypt the path

If choosing Algolia, please install @reimujs/hexo-algoliasearch

1
npm install @reimujs/hexo-algoliasearch --save

And refer to its README to complete the configuration of the Algolia account, and add the following configuration to the outer _config.yml

Note: The search jump link is a permanent link, so please make sure the url in the outer _config.yml is filled in correctly.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
algolia:
  appId: "your applicationID"
  apiKey: "your apiKey"
  adminApiKey: "your adminApiKey"
  indexName: "your indexName"
  chunkSize: 5000
  fields:
    - content:strip:truncate,0,500
    - excerpt:strip
    - gallery
    - permalink
    - photos
    - slug
    - tags
    - title

In the inner _config_yml, set algolia_search.enable to true

1
2
algolia_search:
  enable: true

After version 1.5.0, the theme has built-in hexo-generator-search, so there is no need to install hexo-generator-search separately.

This theme comes with hexo-generator-search built-in. If you choose to use local search, please set generator_search.enable to true in the inner _config.yml. For other configurations, refer to hexo-generator-search.

1
2
3
4
generator_search:
  enable: true
  field: post
  content: true

Math Formulas

Please install @reimujs/hexo-renderer-markdown-it-plus

1
2
npm uninstall hexo-renderer-marked --save
npm install @reimujs/hexo-renderer-markdown-it-plus --save

By default, it is turned off. In the inner _config.yml, set math.enable to true to enable math formula support.

Note: Do not enable both KaTeX and MathJax3 at the same time.

KaTeX

If you want server-side rendering, in the inner _config.yml, set math.katex.enable to true

1
2
3
4
5
math:
  enable: true
  katex:
    enable: true
    autoRender: false

If you want client-side rendering, in the inner _config.yml, set math.katex.enable to true and set autoRender to true

1
2
3
4
5
math:
  enable: true
  katex:
    enable: true
    autoRender: true

Add the following configuration to the outer _config.yml

1
2
markdown_it_plus:
  rawLaTeX: true

MathJax3

If you want to use MathJax3, in the inner _config.yml, set math.mathjax.enable to true

1
2
3
4
5
math:
  enable: true
  mathjax:
    enable: true
    options: # MathJax configuration

Add the following configuration to the outer _config.yml

1
2
markdown_it_plus:
  rawLaTeX: true

Mermaid Flowcharts

Please install hexo-filter-mermaid-diagrams

1
npm install hexo-filter-mermaid-diagrams --save

In the inner _config_yml, set mermaid.enable to true

1
2
mermaid:
  enable: true

And add mermaid: true to the front-matter of articles that require mermaid (This is different from other configurations, please note!)

1
2
3
4
---
title: Hello World
mermaid: true
---

RSS

Please install hexo-generator-feed

1
npm install hexo-generator-feed --save

And refer to its README to complete the feed configuration in the outer _config.yml
Fill in the generated xml in the inner _config.yml

1
rss: atom.xml

i18n

This theme provides four languages by default: en, zh-CN, zh-TW, and ja. You can switch the language by modifying the language in the outer _config.yml.

1
language: zh-CN

The following is an experimental feature and may contain bugs.

v1.4.0+ experimentally introduced hexo-generator-i18n and added multi-language switching functionality. You can configure i18n in the inner _config.yml to add custom languages. The configuration can be referenced from hexo-generator-i18n:

1
2
3
4
5
i18n:
  enable: false # false | true
  type: [page, post]
  generator: [archive, category, tag, index]
  languages: [zh-CN, en] # List of languages, the first one is the default language

For multilingual support in posts, you can add lang in the Front-matter to specify languages other than the default language (the default language does not need to be added).

1
lang: en

The above will generate a page at /en/:permalink.

For multilingual support in pages, you can directly create a folder for the corresponding language in the source directory and place an index.md file inside it, such as source/en/about/index.md. This will generate a page at /en/about.

How to Add Multilingual Support to Hexo
How to Add Multilingual Support to Hexo
Hexo, as a static blog framework, has limited native support for multiple languages and only supports generating single-language websites. To address the need for dynamic language switching, communit

Icons

Icons default to the iconfont provided by this project (v0.1.3+)

1
icon_font: 4552607_bq08450reo

If you want to continue using fontawesome icons, set icon_font to false, and it will use the corresponding fontawesome in vendor

1
2
3
4
5
6
7
8
fontawesome:
  high_priority:
    - webcache|@fortawesome/fontawesome-free@6.5.1/css/regular.min.css
    - webcache|@fortawesome/fontawesome-free@6.5.1/css/solid.min.css
  low_priority:
    - webcache|@fortawesome/fontawesome-free@6.5.1/css/brands.min.css
    - webcache|@fortawesome/fontawesome-free@6.5.1/css/v5-font-face.min.css
    - webcache|@fortawesome/fontawesome-free@6.5.1/css/v4-font-face.min.css

Extended Features

Dark Mode

The default setting is auto, which automatically switches based on the user’s system settings. It can be set to true or false to change the default state.

1
2
3
4
5
dark_mode:
  # true means that the dark mode is enabled by default
  # false means that the dark mode is disabled by default
  # auto means that the dark mode is automatically switched according to the system settings
  enable: auto # true | false | auto

Pace Progress Bar

Enabled by default

1
2
pace:
  enable: true

Firework Mouse Effects

Enabled by default

1
2
firework:
  enable: true

For specific configurations, please refer to mouse-firework

pjax

Disabled by default

1
2
pjax:
  enable: false

pjax was introduced in v0.0.10 for users who need to add music players or other SPA features. After several iterations, it has become relatively stable, but there may still be issues such as scripts not executing, scripts executing repeatedly, or page rendering errors. Please consider carefully before enabling!

PJAX cannot be used with relative_link: true!

ServiceWorker

Disabled by default

1
2
service_worker:
  enable: false

Live2D

Disabled by default

1
2
3
live2d:
  enable: false
  position: left # left | right

Live2D Widgets

Disabled by default

1
2
3
live2d_widgets:
  enable: false
  position: left # left | right

Reimu Mouse Pointer

Enabled by default

1
reimu_cursor: true

Responsive Banner (v0.2.0+)

Disabled by default. Enabling it and providing corresponding images and media queries can improve LCP on mobile devices to some extent.

1
2
3
4
5
6
7
8
9
banner_srcset:
enable: false
srcset:
  - src: "/images/banner-600w.webp"
    media: "(max-width: 479px)"
  - src: "/images/banner-800w.webp"
    media: "(max-width: 799px)"
  - src: "/images/banner.webp"
    media: "(min-width: 800px)"

Article Copyright Notice (v0.2.0+)

Disabled by default

1
2
3
4
5
6
7
8
9
article_copyright:
enable: false # Show copyright card?
content:
  author: # true | false Show author in copyright card?
  link: # true | false Show link in copyright card?
  title: # true | false Show title in copyright card?
  date: # true | false Show creation date in copyright card?
  updated: # true | false Show update date in copyright card?
  license: # true | false Show license in copyright card?

Additionally, it can be controlled via the article’s front-matter, which has higher priority than global configuration.

1
2
3
---
copyright: true # Show copyright card?
---

Enabled by default. Enabling it can preload links while the user stays on the page, improving user experience.

1
2
3
4
5
quicklink:
  enable: true
  timeout: 3000 # Preload timeout
  priority: true # Whether to prioritize loading
  ignores: [] # Links to ignore, only supports strings

Article Outdated Notice (v0.2.4+)

Disabled by default

1
2
3
4
outdate:
  enable: false
  daysAgo: 180 # Articles older than this number of days are considered outdated
  message: This article was last updated {time} ago. Please note that the content may have changed.

Sponsorship (v0.3.2+)

Disabled by default

1
2
3
4
5
6
7
8
9
10
sponsor:
  enable: false # Show sponsorship QR code?
  tip: Buy the author a coffee! # Sponsorship tip
  icon:
    url: "../images/taichi.png" # Sponsorship icon, relative path to css/style.css, so you need to go up one level to find the images folder
    rotate: true # Whether to rotate the icon
    mask: true # Whether to use the image as a mask (i.e., only show the outline of the png image)
  qr:
    - name: Alipay # QR code name
      src: "/sponsor/alipay.jpg" # QR code path, please fill in yourself

Additionally, it can be controlled via the article’s front-matter, which has higher priority than global configuration.

1
2
3
---
sponsor: true # Show sponsorship QR code?
---

Homepage Category Cards (v1.0.0+)

Disabled by default. Enabling it can display category cards on the homepage, replacing the category widget.

1
2
3
4
5
6
7
home_categories:
  enable: false # Show homepage category cards?
  content:
    - categories: # Category name, format is the same as categories in front-matter, can be a string (single-level category) or array (multi-level category)
      cover: # Card cover, if not filled, a random cover will be used
    - categories:
      cover:

Music Player (v1.2.0+)

It is recommended to enable Pjax before using, otherwise the player may automatically pause.

Using Aplayer + Meting (optional), disabled by default.

Pure Aplayer

Set player.aplayer.enable to true, and configure player.aplayer.options according to Aplayer Docs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
player:
  aplayer:
    enable: true
    options:
      audio: [] # audio list
      fixed:
      autoplay:
      loop:
      order:
      preload: 
      volume:
      mutex:
      listFolded:
      lrcType:
Aplayer + Meting

Set both player.aplayer.enable and player.meting.enable to true, and configure player.meting.options according to Meting Docs, player.aplayer.options is the Aplayer configuration.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
player:
  aplayer:
    enable: true
    options:
      audio: [] # this option will be overwritten by meting
      fixed:
      autoplay:
      loop:
      order:
      preload: 
      volume:
      mutex:
      listFolded:
      lrcType:
  meting:
    enable: true
    meting_api: # custom api
    options:
      id: 
      server: 
      type: 
      auto:

Share Links/Cards (v1.3.0+)

Disabled by default. Currently supports facebook, twitter, linkedin, reddit, weibo, qq, weixin.

1
2
3
4
5
6
7
8
share:
  # - facebook
  # - twitter
  # - linkedin
  # - reddit
  # - weibo
  # - qq
  # - weixin

In weixin mode, a share card with a QR code will be generated, which can be saved locally and shared on WeChat Moments (Note: When the article cover has cross-origin issues, html-to-image cannot correctly generate a card with images!)

Built-in Card Tag Plugins

1
{% friendsLink path %}

The first parameter path is the path to the friend link yaml.

1
{% postLinkCard slug [cover]|"auto" [escape] %}

The first parameter is the article’s slug; the second parameter (optional) is the cover displayed on the card, if set to auto, the blog’s banner will be used automatically; the third parameter (optional) indicates whether the article title is escaped.

slug generation algorithm: https://github.com/hexojs/hexo-util/blob/master/lib/slugize.ts
Simply put, it removes invisible characters from the article title, replaces special characters \s~!@#$%^&*()\-_+=[]{}|\;:"'<>,.?/ with the separator -, merges consecutive separators, and removes leading and trailing separators.

1
{% externalLinkCard title link [cover]|"auto" %}

The first parameter is the article’s title; the second parameter is the external link to the article, the third parameter (optional) is the cover displayed on the card, if set to auto, the default cover will be used.

Custom Containers

This theme provides custom container functionality similar to Vitepress. Before using it, you need to install @reimujs/hexo-renderer-markdown-it-plus and set markdown.container to true in the inner _config.yml.

1
2
markdown:
  container: true

Usage is as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::

::: danger STOP
Danger zone, do not proceed
:::

::: details
This is a details block.
:::

Customizing the Theme

hexo-theme-reimu supports high levels of customization. You can customize your theme by modifying _config.yml.

How to customize your hexo-theme-reimu
How to customize your hexo-theme-reimu
This article introduces how to customize your **hexo-theme-reimu** for versions **v1.0.0+** of the theme. ## Customizing Theme Colors The **hexo-theme-reimu** theme supports customizing theme colo

Vendor

vendor is used to store some third-party resources, such as fontawesome, iconfont, katex, mathjax, etc.

The vendor structure of hexo-theme-reimu is very flexible, supporting the following forms:

  • :cdn|:package@:version/:file: Use CDN acceleration, such as cdn_jsdelivr_gh|katex@0.13.11/dist/katex.min.css, :cdn can be configured in vendor. Currently, the following CDN sources are included:
    1
    2
    3
    4
    5
    6
    cdn_jsdelivr_gh: https://cdn.jsdelivr.net/gh/ # Only for github acceleration
    cdn_jsdelivr_npm: https://cdn.jsdelivr.net/npm/ # Only for npm acceleration
    fastly_jsdelivr_gh: https://fastly.jsdelivr.net/gh/ # Only for github acceleration
    fastly_jsdelivr_npm: https://fastly.jsdelivr.net/npm/ # Only for npm acceleration
    unpkg: https://unpkg.com/ # Only for npm acceleration
    webcache: https://npm.webcache.cn/ # Only for npm acceleration
    Users can switch CDN sources based on network conditions.
  • https:// prefix: Use absolute links directly, such as https://cdn.jsdelivr.net/npm/katex@0.13.11/dist/katex.min.css
  • / prefix: Local resources, you can place resources in the source folder at the same level as _posts, and then use paths like /katex.min.css to reference them.

Additionally, vendor supports SRI verification. You can use SHA-384 in vendor to verify the integrity of resources, such as:

1
2
3
4
5
js:
  clipboard: # Use SRI verification
    src: webcache|clipboard@2.0.11/dist/clipboard.min.js
    integrity: sha384-J08i8An/QeARD9ExYpvphB8BsyOj3Gh2TSh1aLINKO3L0cMSH2dN3E22zFoXEi0Q
  lazysizes: webcache|lazysizes@5.3.2/lazysizes.min.js # Do not use SRI verification

Both forms are supported. It is recommended to use SRI verification for external CDN resources to ensure resource integrity.

QA

Music still pauses automatically after page jumps with pjax enabled

Under investigation, v1.3.0 theoretically fixed some issues.

Avatar not displaying correctly

Refer to reimu-template to ensure the avatar is placed in /source/_data/avatar/ and the name matches the configuration (Note: This is the source folder in the blog root directory, not the source folder in the theme!)

About and Friends pages display garbled text, no styles

Refer to reimu-template to ensure about and friend are placed in /source/ (Note: This is the source folder in the blog root directory, not the source folder in the theme!)

Gitalk keeps loading

Refer to gitalk#514, some APIs that Gitalk depends on are blocked, causing it to fail to load.

The comment section mentions that replacing the Gitalk js address can solve the problem, but this theme will not provide such a solution due to potential security risks.

I still have strange issues

First, try the hexo clean method. If the problem persists, try cloning reimu-template directly and make modifications based on it. If the issue still exists, please ask a question on Github issue and provide detailed error information/reproduction steps. It is not recommended to report issues in the comment section as it is inconvenient for code formatting.