计软杂谈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.11.0 Unreleased ### Features - Added support for the [Disqus]

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

Features

Basic Features

  • ✨ Full blog functionality
  • 🔄 Compatible with Hexo 6+
  • 📱 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 systems support:
    • Valine
    • Waline
    • Twikoo
    • Gitalk
    • Giscus
    • Disqus

Statistics & Analytics

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

Media & Interactive Features

  • 🎵 Music player support:
    • Aplayer
    • Meting
  • 🖼️ Lazy loading for images
  • ⚡ Loading animations
  • 🖱️ Mouse effects:
    • Animation effects
    • Reimu cursor style
  • 👾 Live2D / Live2D-widgets integration
  • 📑 Table of Contents
  • 🔄 PJAX support
  • 🔧 ServiceWorker implementation
  • 📰 RSS feed

Design & Customization

  • 🎨 Icon support:
    • Iconfont
    • FontAwesome7
  • 🔗 Built-in tag plugins:
    • Internal links
    • External links
    • Friend links
    • Heatmap
    • Tag Roulette
  • 🎨 Dynamic theme color adaptation
  • 🎨 Custom Containers
  • ©️ Article copyright declaration
  • 🌐 Custom CDN source configuration
  • 📜 Custom Font Family
  • 🎨 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
---

Article Summary

Disabled by default. You can choose to display the article summary in the subtitle or at the beginning of the article.

1
2
3
summary:
  enable: false
  style: 'subtitle' # 'subtitle' or 'blockquote'

Default on the right. You can modify it in the inner _config.yml.

1
sidebar: right # left | right

Additionally, you can control it through the article’s front-matter, which takes precedence over the global configuration.

1
2
3
---
sidebar: left # left | right
---

TOC

Default enabled. You can modify it in the inner _config.yml.

1
toc: true # true | false

Additionally, you can control it through the article’s front-matter, which takes precedence over the global configuration.

1
2
3
---
toc: true # true | false
---

You can also configure the behavior of the TOC through the following configuration:

1
2
3
4
toc_options:
  list_number: true # Whether to display the list number
  min_depth: 1 # Minimum depth
  max_depth: 6 # Maximum depth

You can configure the social links in the sidebar in the inner _config.yml.

1
2
3
4
social:
  # github: https://github.com/yourname
  # bilibili: https://space.bilibili.com/yourname
  # ...

Widgets

You can configure the widgets in the sidebar in the inner _config.yml.

1
2
3
4
5
6
widgets:
  # - category
  # - tag
  # - tagcloud
  # - archive
  # - recent_posts

You can also configure the behavior of the widgets through the following configuration:

1
2
3
4
5
archive_type: "monthly" # monthly | yearly
show_count: false
tag_limits:
recent_posts_limits: 5
tagcloud_limits:

Basic Information

The footer section allows you to configure basic display information and statistics.

1
2
3
4
5
footer:
  since: 2020 # The starting year displayed in the copyright information (e.g., 2020-current year)
  powered: true # Whether to display copyright information
  count: true # Whether to display word count and reading time statistics
  busuanzi: true # Whether to enable Busuanzi visitor counting statistics

ICP Filing

For websites hosted in mainland China, you can display ICP filing information as required by regulations.

1
2
3
4
icp:
  icpnumber: # ICP filing number
  beian: # Public Security Bureau filing number
  recordcode: # Record code parameter from the Public Security Bureau filing link

Moe ICP Filing (v1.9.1+)

Moe ICP Filing

1
2
moe_icp:
  icpnumber: # Moe ICP filing number

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 copyright notice will be added after the copied content.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
clipboard:
  success: 
    en: Copy successfully (*^▽^*)
    zh-CN: 复制成功 (*^▽^*)
    zh-TW: 複製成功 (*^▽^*)
    ja: コピー成功 (*^▽^*)
  fail: 
    en: Copy failed (ﾟ⊿ﾟ)ﾂ
    zh-CN: 复制失败 (ﾟ⊿ﾟ)ﾂ
    zh-TW: 複製失敗 (ﾟ⊿ﾟ)ﾂ
    ja: コピー失敗 (ﾟ⊿ﾟ)ﾂ
  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.

Support for multiple comment systems simultaneously after version 1.7.0+

Global comment system configuration:

1
2
3
4
5
6
7
comment:
  title: # Title of the comment box  
    en: Leave a comment
    zh-CN: 说些什么吧！
    zh-TW: 說些什麼吧！
    ja: コメントを残す
  default: waline # Default comment system used when multiple are enabled

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
waline:
  enable: true
  serverURL: "your server url"
  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
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

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 using Disqus
Please set disqus.enable to true in the inner _config.yml, and fill in your shortname

1
2
3
4
disqus:
  enable: true
  shortname: "your shortname"
  count: true # Whether to enable comment count statistics

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
9
10
11
12
13
fontawesome:
  high_priority:
    - src: webcache|@fortawesome/fontawesome-free@6.5.1/css/regular.min.css
      integrity: sha384-k5640LgghgAohDLPwSqVWa96yQwWouT6wsAL+J1g0CFJVITNKYkIh1XpPLYKQe7Y
    - src: webcache|@fortawesome/fontawesome-free@6.5.1/css/solid.min.css
      integrity: sha384-8yO/A/BtltnG0hDxdwmmkza8UAleyDoAD1FhXiH6rsOQQsCho1P6WZP9TpBBH3YP
  low_priority:
    - src: webcache|@fortawesome/fontawesome-free@6.5.1/css/brands.min.css
      integrity: sha384-/BRyRRN0wxxRgh/DAXU621go9pdoMHl6LFPiX5Pp8PZYZlKBQCDXj9X9DHx6LOud
    - src: webcache|@fortawesome/fontawesome-free@6.5.1/css/v5-font-face.min.css
      integrity: sha384-/mBKnLlGtog8q2qQrgugURRDV+iHWHAPvM5KulYXT1C2ErKOKkBI0vbff8ZPq7rL
    - src: webcache|@fortawesome/fontawesome-free@6.5.1/css/v4-font-face.min.css
      integrity: sha384-d2Yn1/9Iw78r3oqwk5B+EcpRcmepXR5LyhmRF2a+WoSe9mpRGvVk0ZviFwDGDOTO

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
10
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?
  license_type: by-nc-sa # https://creativecommons.org/licenses

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
5
6
7
8
outdate:
  enable: false
  daysAgo: 180 # Articles older than this number of days are considered outdated
  message:
    en: This article was last updated on {time}. Please note that the content may no longer be applicable.
    zh-CN: 本文最后更新于 {time}，请注意文中内容可能已不适用。
    zh-TW: 本文最後更新於 {time}，請注意文中內容可能已不適用。
    ja: この記事は最終更新日：{time}。記載内容が現在有効でない可能性がありますのでご注意ください。

Sponsorship (v0.3.2+)

Disabled by default

1
2
3
4
5
6
7
8
9
10
11
12
13
14
sponsor:
  enable: false # Show sponsorship QR code?
  tip: # Sponsorship tip
    zh-CN: 请作者喝杯咖啡吧
    zh-TW: 請作者喝杯咖啡吧
    en: Buy me a coffee
    ja: コーヒーを買ってください
  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.

Music Player Position (v1.9.1+)

Default is after sidebar

1
2
player:
  position: before_sidebar # before_sidebar / after_sidebar / after_widget
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, snapdom cannot correctly generate a card with images!)

Injector (v1.5.1+)

Used to inject custom code, similar to Hexo#Injector, supports head, body and sidebar injection

1
2
3
4
5
6
7
injector:
  head_begin: # Inject code snippet right after <head>
  head_end: # Inject code snippet right before </head>
  body_begin: # Inject code snippet right after <body>
  body_end: # Inject code snippet right before </body>
  sidebar_begin: # Inject code snippet right after <aside>
  sidebar_end: # Inject code snippet right before </aside>

Triangle Badge (v1.10.2+)

Disabled by default. When enabled, it will display a triangle badge in the upper right corner, supporting custom links and icons.

1
2
3
4
triangle_badge:
  enable: false
  icon: github # Same as the icon in the social config
  link: https://github.com/D-Sketon/hexo-theme-reimu

Built-in 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.

Heat Map Card Article Heatmap (v1.7.0+)

1
{% heatMapCard levelStandard %}

The first parameter is the level standard for the heatmap (graded based on the word count of the articles), with the default value being "1000,5000,10000".

tagRoulette (v1.9.0+)

1
{% heatMapCard tags icon %}

tagRoulette is an interactive element that provides a random tag display feature. When the button is clicked, a tag is randomly selected and displayed from a predefined pool of tags.

  • tags: Optional parameter specifying the tag pool. Multiple tags should be separated by English commas (,). If not provided, a few example tags will be used by default. Example: tags="memory decline, loss of expression, increased laziness, numbness, so sleepy"
  • icon: Optional parameter to customize the trigger button’s icon. Default: 🕹️ (game controller emoji). Can be replaced with any emoji or text, such as 🎲, 🎯, 🔄, etc.

tabs (v1.11.0+)

1
2
3
4
5
6
{% tabs [activeTab] ["center"] %}
<!-- tabName -->
Tab content
<!-- tabName -->
Tab content
{% endtabs %}

Adapted from the next, volantis, and stellar themes, this feature supports creating tabbed switching effects within articles.

  • activeTab: Optional parameter, specifies the default active tab index (counting starts from 1). Default is 1.
  • “center”: Optional parameter, specifies that tab titles should be center-aligned. Default is left-aligned.
  • tabName: The title of each tab, must be wrapped in . Supports displaying icons using @ + icon hexadecimal code. Examples:
    • Title only:
    • Icon only:
    • Icon + Title: 
1
2
3
4
5
{% gallery %}
![alt text](image_url1)
![alt text](image_url2)
...
{% endgallery %}

Display multiple images in a photo wall format, supporting automatic arrangement and responsive layout.

Custom Containers

This theme provides custom container functionality similar to Vitepress. Before using it, you need to install @reimujs/hexo-renderer-markdown-it-plus.

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
24
25
26
27
::: info
This is an info box.
:::

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

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

::: important
This is an important box.
:::

::: 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. ## Dynamic Theme Color Adaptation (Experimental Feature in v1.7.0+) Disabled by default. W

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.

Appendix

Front-matter Fields

meta Description Type Value Logic Version
title Title string Article file name Hexo Built-in
date Creation Date date File creation date Hexo Built-in
updated Update Date date File update date Hexo Built-in
tags Tags string[] | string[][] - Hexo Built-in
categories Categories string[] | string[][] - Hexo Built-in
permalink Override the article’s permanent link string - Hexo Built-in
excerpt Article Excerpt string - Hexo Built-in
description Article Description string - 0.0.1
link Directs the article to an external link string - 0.0.1
sticky Whether to pin the article boolean false 0.0.1
photos Article photo gallery string[] - 0.0.1
mermaid Whether to enable mermaid (requires configuration with mermaid config) boolean false 0.2.0
copyright Whether to enable article copyright notice boolean Defaults to global config if not provided 0.3.1
sponsor Whether to enable article sponsorship boolean Defaults to global config if not provided 0.3.2
comments Whether to enable article comments boolean Defaults to global config if not provided 0.3.2
cover Article cover https://example.com | false | rgb(255,117,117) Defaults to global config if not provided 0.0.7
sidebar Article sidebar position false | 'left' | 'right' Defaults to global config if not provided 1.3.0
lang Article language (requires configuration with i18n config) string - 1.4.0
toc Whether to enable article table of contents boolean Defaults to global config if not provided 1.6.0
outdated Whether the article is outdated boolean Defaults to global config if not provided 1.10.1
author Article author (used for article copyright and sharing cards) string Defaults to global config if not provided 1.10.2
keywords Article keywords for SEO string[] | string Defaults to global config if not provided 1.10.4

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.

Leave a comment

waline