Warning
Versions below v1.0.0 have been deprecated. Please upgrade to version v1.0.0 or above as soon as possible.
A Hakurei Reimu style Hexo theme.
A combination of landscape、Tangyuxian and Shoka themes.
framework | repository | version | stars |
---|---|---|---|
Hexo | hexo-theme-reimu | ||
Astro | astro-theme-reimu | ||
Hugo | hugo-theme-reimu |
ISSUE and PR Welcome!
- ✨ Full blog functionality
- 🔄 Compatible with Hexo6+
- 📱 Responsive layout
- 🌙 Dark mode support
🅰️ i18n support
- 🖥️ Code highlighting and copying
- ➗ KaTeX / MathJax3 math formula support
- 📊 Mermaid flowchart support
- 🔍 Algolia search integration
- 🔍 Local search integration
- 💬 Multiple comment systems support:
- Valine
- Waline
- Twikoo
- Gitalk
- Giscus
- 📊 Article reading statistics (Valine / Waline)
- 👥 Visitor statistics (Busuanzi)
- 🎵 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 (TOC)
- 🔄 PJAX support
- 🔧 ServiceWorker implementation
- 📰 RSS feed
- 🎨 Icon support:
- Iconfont
- FontAwesome
- 🔗 Custom tag plugins for:
- Internal links
- External links
- Friend links
- 🎨 Custom Containers
- ©️ Article copyright declaration
- 🌐 Custom CDN source configuration
- 🎨 Share card functionality
For beginners, you can directly use reimu-template. It comes pre-installed with hexo, hexo-theme-reimu and other functional packages. You only need to clone the repository, install dependencies, and modify the configuration to get a basic blog!
Using npm
npm install hexo-theme-reimu --save
Or clone this repository directly to the /themes
folder and rename it to reimu
git clone https://github.com/D-Sketon/hexo-theme-reimu.git
And modify the theme in _config.yml
# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
theme: reimu
Basic structure
To ensure correct display, please refer to _example
and create _data
, about
, and friend
folders in source
(Note: This is the source
folder in your blog's root directory, not the one in the theme!)
- The
avatar
folder stores the author's avatar, default namedavatar.webp
. You can configure it in the inner_config.yml
as follows:
avatar: "avatar.webp" # By default, it looks for the avatar in the avatar folder. Do not include the path, or it will result in a 404 error
- The
covers
folder stores article cover images - The
covers.yml
stores article cover URLs
index.md
serves as the About page
index.md
serves as the Friends page. Fill in friend link information in _data.yml
to display corresponding friend cards on the page
Cover Images, Banner and Favicon
The cover image display logic is as follows:
- If the article's Front matter contains a cover URL, both the article header image and homepage thumbnail will display this URL
---
title: Hello World
cover: https://example.com
---
- If the article's Front matter contains cover:
false
, no header image will be displayed for that article (the homepage will still show a random image)
---
title: Hello World
cover: false
---
- If the article's Front matter contains cover:
rgb(xxx,xxx,xxx)
, the article's header image will be a gradient of that solid color (the homepage will still show a random image)
---
title: Hello World
cover: rgb(255,117,117)
---
- Otherwise, it will search for images in the
covers
folder andcovers.yml
and randomly select one - If none of the above files exist, it will display the default banner image
The banner image is stored at themes/reimu/source/images/banner.webp
, and can be modified in the inner _config.yml
:
banner: "/images/banner.webp"
The favicon is stored at themes/reimu/source/images/favicon.ico
, and can be modified in the inner _config.yml
:
favicon: "/images/favicon.ico"
Add sticky: true
to the article's Front-matter to pin it:
---
title: Hello World
sticky: true
---
Code Blocks
To ensure proper display of code blocks, make sure your outer _config.yml
has the following configuration:
(Hexo <7.0.0)
highlight:
enable: true
wrap: true
hljs: false
prismjs:
enable: false
(Hexo >=7.0.0)
syntax_highlighter: highlight.js
highlight:
wrap: true
hljs: false
Code blocks also provide a code copying feature - click the copy button in the top right corner of the code block to copy the code. You can configure the copy functionality in the inner _config.yml
.
success
is the prompt shown when copying is successful, fail
is shown when copying fails. Additionally, you can configure copyright notices - when the copied text exceeds count
characters, the content
copyright notice will be added after the copied content.
clipboard:
success: 复制成功(*^▽^*)
fail: 复制失败 (゚⊿゚)ツ
copyright:
enable: false
count: 50 # Add copyright notice when character count exceeds this number
content: 本文版权:本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!
v1.1.0 added configuration to control the default expansion state of code blocks. expand
can be set to true
, false
, or a number - the number indicates that code blocks will be collapsed by default when the number of lines exceeds this value.
code_block:
expand: true # true | false | number
Site comments
Site comments can be individually controlled for each article using
comments
in the Front matter.
Whencomments
isfalse
, comments won't be displayed. When it'strue
or not specified, the display will be determined by the_config.yml
configuration.
If using Valine
Please refer to their official documentation to complete the LeanCloud
configuration, then set valine.enable
to true
in the inner _config.yml
and fill in your appId
and appKey
valine:
enable: true
appId: "your appId"
appKey: "your appKey"
If using Waline
Please refer to their official documentation to complete the LeanCloud
configuration, then set waline.enable
to true
in the inner _config.yml
and fill in your serverURL
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/[email protected]/weibo
- https://unpkg.com/@waline/[email protected]/alus
- https://unpkg.com/@waline/[email protected]/bilibili
- https://unpkg.com/@waline/[email protected]/qq
- https://unpkg.com/@waline/[email protected]/tieba
- https://unpkg.com/@waline/[email protected]/tw-emoji
meta:
- nick
- mail
- link
requiredMeta:
- nick
- mail
wordLimit: 0
pageSize: 10
pageview: true
If using twikoo
Please refer to their official documentation to complete Tencent Cloud or Vercel deployment, then set twikoo.enable
to true
in the inner _config.yml
and fill in your envId
twikoo:
enable: true
envId: # For Tencent Cloud environment, fill in envId; For Vercel environment, fill in the URL (https://xxx.vercel.app)
region:
If using giscus
Please refer to the documentation to complete repository configuration, then set giscus.enable
to true
in the inner _config.yml
and fill in the corresponding data
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 their official documentation to complete repository configuration, then set gitalk.enable
to true
in the inner _config.yml
and fill in the corresponding data
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
Site search
If choosing Algolia, please install @reimujs/hexo-algoliasearch
npm install @reimujs/hexo-algoliasearch --save
Then refer to its README to complete the Algolia
account configuration, and add the following configuration to the outer _config.yml
Note: The search redirect link is a permanent link, so please ensure the
url
in the outer_config.yml
is filled in correctly.
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
algolia_search:
enable: true
After version 1.5.0, the theme has built-in
hexo-generator-search
, so there is no need to installhexo-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.
generator_search:
enable: true
field: post
content: true
Mathematical formulas
please install @reimujs/hexo-renderer-markdown-it-plus
npm uninstall hexo-renderer-marked --save
npm install @reimujs/hexo-renderer-markdown-it-plus --save
Mathematical formula support is disabled by default. To enable it, set math.enable
to true
in the inner _config.yml
Note: Do not enable both KaTeX and MathJax3 simultaneously
For server-side rendering, set math.katex.enable
to true
in the inner _config.yml
math:
enable: true
katex:
enable: true
autoRender: false
For client-side rendering, set both math.katex.enable
and autoRender
to true
in the inner _config.yml
math:
enable: true
katex:
enable: true
autoRender: true
Add the following configuration to the outer _config.yml
markdown_it_plus:
rawLaTeX: true
To use MathJax3, set math.mathjax.enable
to true
in the inner _config.yml
math:
enable: true
mathjax:
enable: true
options: # MathJax3 Options
Add the following configuration to the outer _config.yml
markdown_it_plus:
rawLaTeX: true
Mermaid Diagrams
Please install hexo-filter-mermaid-diagrams
npm install hexo-filter-mermaid-diagrams --save
Set mermaid.enable
to true
in the inner _config.yml
mermaid:
enable: true
And add mermaid: true
to the front-matter of any article where you want to use mermaid diagrams
---
title: Hello World
mermaid: true
---
RSS
Please install hexo-generator-feed
npm install hexo-generator-feed --save
Refer to its README to complete the feed
configuration in the outer _config.yml
Then add the generated xml
path to the inner _config.yml
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
.
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:
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).
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
.
For more information, please refer to How to add multi-language support to Hexo
Icon
By default, this theme uses its own provided iconfont (v0.1.3+)
icon_font: 4552607_0khxww3tj3q9
If you want to continue using fontawesome icons, set icon_font
to false
. This will use the corresponding fontawesome from the vendor
fontawesome:
high_priority:
- webcache|@fortawesome/[email protected]/css/regular.min.css
- webcache|@fortawesome/[email protected]/css/solid.min.css
low_priority:
- webcache|@fortawesome/[email protected]/css/brands.min.css
- webcache|@fortawesome/[email protected]/css/v5-font-face.min.css
- webcache|@fortawesome/[email protected]/css/v4-font-face.min.css
Extended features
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.
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
Enabled by default
pace:
enable: true
Enabled by default
firework:
enable: true
For detailed configuration, please check mouse-firework
Disabled by default
pjax:
enable: false
PJAX was introduced in v0.0.10 for users who need SPA features like music players. After several iterations, it's mostly stable but may still cause issues like script execution failures, script duplicate execution, or page rendering problems. Please consider carefully!
PJAX cannot be used with
relative_link: true
!
Disabled by default
service_worker:
enable: false
Disabled by default
live2d:
enable: false
position: left # left | right
Disabled by default
live2d_widgets:
enable: false
position: left # left | right
Enabled by default
reimu_cursor:
enable: true
cursor:
default: ../images/cursor/reimu-cursor-default.png
pointer: ../images/cursor/reimu-cursor-pointer.png
text: ../images/cursor/reimu-cursor-text.png
Disabled by default. When enabled and provided with corresponding image sizes and media queries, it can improve mobile LCP performance
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)"
Disabled by default
article_copyright:
enable: false # Display 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, this can be controlled through article front-matter, which takes precedence over global configuration
---
copyright: true # Display copyright card?
---
Disabled by default. When enabled, it preloads links while users stay on the page to improve user experience
quicklink:
enable: false
timeout: 3000 # Preload timeout
priority: true # Whether to prioritize loading the page
ignores: [] # Ignore the specified link, supports strings only
Disabled by default
outdate:
enable: false
daysAgo: 180 # How many days old before an article is considered outdated
message: 本文最后更新于 {time},请注意文中内容可能已经发生变化。
Disabled by default
sponsor:
enable: false # Display sponsorship QR code?
tip: Buy the author a coffee! # Sponsorship prompt
icon:
url: "../images/taichi.png" # Sponsorship icon, path relative to css/style.css, so need to go up one level to find images folder
rotate: true # Rotate icon?
mask: true # Use image as mask (only show PNG image outline)?
qr:
- name: Alipay # QR code name
src: "/sponsor/alipay.jpg" # QR code path, please fill in yourself
Additionally, this can be controlled through article front-matter, which takes precedence over global configuration
---
sponsor: true # Display sponsorship QR code?
---
Disabled by default. When enabled, displays category cards on homepage as an alternative to widget categories
home_categories:
enable: false # Display home categories card?
content:
- categories: # Category name, format matches categories in front-matter, can be string (single-level) or array (multi-level)
cover: # Card cover, uses random cover if not specified
- categories:
cover:
It's recommended to enable Pjax first, otherwise the player may auto-pause
Uses Aplayer + Meting (optional), disabled by default
Set player.aplayer.enable
to true
and configure player.aplayer.options
according to Aplayer Docs
player:
aplayer:
enable: true
options:
audio: [] # audio list
fixed:
autoplay:
loop:
order:
preload:
volume:
mutex:
listFolded:
lrcType:
Set both player.aplayer.enable
and player.meting.enable
to true
, configure player.meting.options
according to Meting Docs, player.aplayer.options
is for Aplayer configuration
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:
Disabled by default, currently supports facebook
, twitter
, linkedin
, reddit
, weibo
, qq
, weixin
.
share:
# - facebook
# - twitter
# - linkedin
# - reddit
# - weibo
# - qq
# - weixin
For weixin
, it generates a share card with QR code that can be saved locally and shared to WeChat Moments (Note: when the article cover has cross-origin issues, html-to-image cannot correctly generate cards with images!)
Built-in Card Tags
{% friendsLink path %}
The first parameter path
indicates the path to the friend links yaml file
{% postLinkCard slug [cover]|"auto" [escape] %}
The first parameter is the article's slug
; the second parameter (optional) is the cover image displayed on the card, if set to auto
it will automatically use the blog's banner
; the third parameter (optional) indicates whether the article title should be escaped
Slug generation algorithm: https://github.com/hexojs/hexo-util/blob/master/lib/slugize.ts In simple terms, it removes invisible characters from the article title and replaces special characters
\s~!@#$%^&*()\-_+=[]{}|\;:"'<>,.?/
with the separator-
, merges consecutive separators and removes leading/trailing separators
{% externalLinkCard title link [cover]|"auto" %}
The first parameter is the article title; the second parameter is the external link to the article; the third parameter (optional) is the cover image displayed on the card, if set to auto
it will automatically use the default cover
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
.
markdown:
container: true
Usage is as follows:
::: 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.
:::
Customize theme
The hexo-theme-reimu theme supports extensive customization. You can customize your theme by modifying _config.yml
.
The hexo-theme-reimu theme supports theme color customization through CSS variables. You can customize your theme colors by modifying CSS variables under the :root
pseudo-class.
The variables file is located at source/css/_variables.styl
. You can find all CSS variables there, but you really only need to modify the variables under these pseudo-classes:
:root
--red-0: hsl(0, 100%, 50%)
--red-1: hsl(0, 100%, 66%)
--red-2: hsl(0, 100%, 74%)
--red-3: hsl(0, 100%, 84%)
--red-4: hsl(0, 100%, 91%)
--red-5: hsl(0, 100%, 95%)
--red-5-5: hsl(0, 100%, 96%)
--red-6: hsl(0, 100%, 98%)
--color-red-6-shadow: hsla(0, 100%, 65%, 0.6)
--color-red-3-shadow: hsla(0, 100%, 65%, 0.3)
[data-theme="dark"]
root
--red-4: hsla(0, 100%, 91%, 0.5)
--red-5: hsla(0, 100%, 95%, 0.2)
--red-5-5: hsla(0, 100%, 96%, 0.1)
--red-6: hsla(0, 100%, 98%, 0.2)
You can define Google Fonts through the following configuration:
# https://fonts.google.com/
font:
article:
- Mulish
- Noto Serif SC
code:
# - Ubuntu Mono
# - Source Code Pro
# - JetBrains Mono
v1.1.0 added local_font
configuration for defining local fonts, which has lower priority than Google Fonts:
local_font:
article:
- "-apple-system"
- PingFang SC
- Microsoft YaHei
- sans-serif
code:
- Menlo
- Monaco
- Consolas
- monospace
v1.0.0 underwent significant refactoring and exposed many configurations for changing the original icons
The menu
configuration structure changed in v1.0.0, allowing users to customize icons. When icon is empty, it defaults to the Taichi icon. You can fill in a hexadecimal number to customize the icon, supporting both FontAwesome and icon font.
menu:
- name: home
url: /
icon: # Defaults to Taichi icon when empty
- name: archives
url: /archives
icon: f0c1 # You can fill in a hexadecimal number to customize the icon, supports FontAwesome and icon font
- name: about
url: /about
icon:
- name: friend
url: /friend
icon:
v1.0.0 added icon
configuration to footer
, top
, and sponsor
configurations for customizing icons.
url
is the path to the icon, relative tocss/style.css
, so you need to go up one level to find the images folder.rotate
determines whether to rotate the icon, defaults totrue
.mask
determines whether to use the image as a mask (only showing PNG image outline), defaults totrue
.
footer:
icon:
url: "../images/taichi.png"
rotate: true
mask: true
top:
icon:
url: "../images/taichi.png"
rotate: true
mask: true
sponsor:
icon:
url: "../images/taichi.png"
rotate: true
mask: true
v1.0.0 added icon
configuration to preloader
for customizing the loading icon. When icon is empty, it defaults to using inline SVG (ensuring first-screen loading speed). You can enter a link to customize the loading icon.
It's not recommended to use oversized icons to avoid affecting loading speed.
preloader:
enable: true
text: 少女祈祷中...
icon: # if the icon is empty, the default svg is used, which is inlined to ensure the loading speed of the first screen. You can fill in a link to customize the loading icon, such as '/images/taichi.png'
v1.0.0 added anchor_icon
configuration for customizing anchor icons, defaults to using the #
icon. You can fill in a hexadecimal number to customize the icon, supporting both FontAwesome and icon font.
anchor_icon: # if the icon is empty, the default # icon is used
v1.3.0 added reimu_cursor.cursor
configuration for customizing cursor icons. You can fill in a path relative to css/style.css
to customize cursor icons.
reimu_cursor:
enable: true
cursor:
default: ../images/cursor/reimu-cursor-default.png
pointer: ../images/cursor/reimu-cursor-pointer.png
text: ../images/cursor/reimu-cursor-text.png
Vendor
vendor
is used to store third-party resources such as fontawesome, iconfont, katex, mathjax, etc.
The vendor
structure in hexo-theme-reimu is very flexible and supports the following formats:
:cdn|:package@:version/:file
: Uses CDN acceleration, for examplecdn_jsdelivr_gh|[email protected]/dist/katex.min.css
. The:cdn
can be configured invendor
. Currently includes the following CDN sources:Users can switch CDN sources based on their network conditions.cdn_jsdelivr_gh: https://cdn.jsdelivr.net/gh/ # GitHub acceleration only cdn_jsdelivr_npm: https://cdn.jsdelivr.net/npm/ # NPM acceleration only fastly_jsdelivr_gh: https://fastly.jsdelivr.net/gh/ # GitHub acceleration only fastly_jsdelivr_npm: https://fastly.jsdelivr.net/npm/ # NPM acceleration only unpkg: https://unpkg.com/ # NPM acceleration only webcache: https://npm.webcache.cn/ # NPM acceleration only
- Starting with
https://
: Uses absolute links directly, such ashttps://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css
- Starting with
/
: Local resources. You can place resources in thesource
folder at the same level as_posts
, then reference them using paths like/katex.min.css
Additionally, vendor
supports SRI (Subresource Integrity) verification. You can use SHA-384
in vendor
to verify resource integrity, for example:
js:
clipboard: # Using SRI verification
src: webcache|[email protected]/dist/clipboard.min.js
integrity: sha384-J08i8An/QeARD9ExYpvphB8BsyOj3Gh2TSh1aLINKO3L0cMSH2dN3E22zFoXEi0Q
lazysizes: webcache|[email protected]/lazysizes.min.js # Without SRI verification
Both formats are supported. It's recommended to use SRI verification for external CDN resources to ensure resource integrity.
MIT