hugo-theme-reimu

💘 博麗霊夢 💘

[演示网站](https://d-sketon.github.io/hugo-theme-reimu) | [迁移指南](https://d-sketon.github.io/20241110/hexo-to-hugo-guide/)

简体中文 | English

A Hakurei Reimu style Hugo theme. Migrated from hexo-theme-reimu.

framework	repository	version	stars
Hexo	hexo-theme-reimu
Astro	astro-theme-reimu
Hugo	hugo-theme-reimu

项目刚刚开始，欢迎提出 Issue 和 PR！

特性

基础功能

✨ 完整的博客功能
🔄 兼容 Hugo 0.116.0 及以上版本
📱 响应式布局
🌙 暗黑模式支持

代码与数学

🖥️ 代码高亮与复制
➗ KaTeX / MathJax3 数学公式支持
📊 Mermaid 流程图支持

搜索与评论

🔍 Algolia 搜索集成
💬 多评论系统支持：
- Valine
- Waline
- Twikoo
- Gitalk
- Giscus

统计与分析

📊 文章阅读统计（Valine / Waline）
👥 访客统计（不蒜子）

媒体与交互功能

🎵 音乐播放器支持：
- Aplayer
- Meting
🖼️ 图片懒加载
⚡ 加载动画
🖱️ 鼠标特效：
- 动画效果
- 灵梦鼠标指针
👾 Live2D / Live2D-widgets 集成

导航与结构

📑 目录导航（TOC）
🔄 PJAX 支持
🔧 ServiceWorker 实现
📰 RSS 订阅

设计与自定义

🎨 图标支持：
- Iconfont
- FontAwesome
🔗 自定义短代码：
- 内部链接
- 外部链接
- 友情链接
©️ 文章版权声明
🌐 自定义 CDN 源配置
🎨 分享卡片功能

安装

cd themes
git clone --single-branch --branch main https://github.com/D-Sketon/hugo-theme-reimu.git

并修改 hugo.toml 中的 theme

theme = 'hugo-theme-reimu'

使用

创建配置

主题配置

在外层 config 文件夹下创建 _default 文件夹，然后将主题内的 config/_default/params.yml 复制到 _default 文件夹下，此文件作为主题配置文件，可在此文件中修改主题配置

数据配置

将主题内的 config/data/ 文件夹内的所有文件复制到外层 data 文件夹下，此文件夹内的文件用于配置主题内的数据：

covers.yml 用于配置随机封面图片
friends.yml 用于配置友链
vendor.yml 用于配置第三方库的 CDN 源

静态资源配置

主题的静态资源（favicon，头图等）位于 static 文件夹内，你可以在外层 static 文件夹下创建相应的文件夹，然后将主题内的文件复制到外层文件夹下，以覆盖主题内的默认文件

总之一句话，不建议直接修改主题内的文件，而是在外层创建相应的文件夹，然后将主题内的文件复制到外层文件夹下，以覆盖主题内的默认文件，这样便于主题升级

语言配置

reimu 支持多语言。如果你想要使用中文，请在 hugo.toml 中添加如下配置

languageCode = 'zh-CN'
defaultContentLanguage = 'zh-CN'
[languages]
[languages.zh-CN]
languageName = '简体中文'
weight = 1

基本结构

为了保证显示正确，请参考 _example 在 content 中建立 archives 和 post 文件夹（里面的 _index.md 不可省略，且注意 post 的 draft 为 true）

post

文章请在此目录下创建，注意 draft 为 true 的文章不会显示在首页

_index.md 用于忽略 post/index.html 的生成，不可省略

about.md

关于页面

friend.md

友链页面

头像、封面、头图和图标

头像、封面、头图和favicon

头像

头像应保存于 static/avatar/avatar.webp，可在 params.yml 中修改文件名

avatar: "avatar.webp"

封面

随机封面图片请参考主题内的 data/covers.yml 文件结构，在外层 data 文件夹下创建 covers.yml 文件，格式如下：

- https://example.com/1.jpg
- https://example.com/2.jpg

封面显示逻辑如下

如果文章的 Front matter 中包含 cover 的 url，则该文章头图和首页缩略图均显示该 url

---
title: Hello World
cover: https://example.com
---

如果文章的 Front matter 中包含 cover 为 false，则该文章不显示头图（首页上仍然是随机图片）

---
title: Hello World
cover: false
---

如果文章的 Front matter 中包含 cover 为 rgb(xxx,xxx,xxx)，则该文章头图为对应的渐变纯色（首页上仍然是随机图片）

---
title: Hello World
cover: rgb(255,117,117)
---

否则查找 data 文件夹中的 covers.yml，并从中随机挑选图片
若上述文件均不存在，则显示头图

头图

头图保存于 themes/hugo-theme-reimu/static/images/banner.webp，可在 params.yml 中修改路径和名字

banner: "images/banner.webp"

Favicon

favicon 保存于 themes/hugo-theme-reimu/static/favicon.ico，可自行覆盖替换

代码块

为保证代码块的正确显示，请保证 hugo.toml 中有如下配置

[markup.highlight]
guessSyntax = true
noClasses = false

代码块同时提供了代码粘贴功能，点击代码块右上角的复制按钮即可复制代码。在 params.yml 中可以对复制功能进行配置。
success 为复制成功时的提示，fail 为复制失败时的提示。此外，可以配置版权声明，当复制的字符数大于 count 时会在复制的内容后面添加 content 版权声明。

clipboard:
  success: 复制成功(*^▽^*)
  fail: 复制失败 (ﾟ⊿ﾟ)ﾂ
  copyright:
    enable: false
    count: 50 # 大于多少字符添加版权声明
    content: 本文版权：本博客所有文章除特别声明外，均采用 BY-NC-SA 许可协议。转载请注明出处！

v0.2.0 添加了配置用于控制代码块的默认展开状态，expand 可以设置为 true、false 或数字，数字表示当代码块的行数大于该数字时默认收缩。

code_block:
  expand: true # true | false | number

站内评论

站内评论可以使用 Front matter 中的 comments 独立控制每篇文章是否显示评论。
当 comments 为 false 时不显示评论，true 或不填时根据 params.yml 的配置决定是否显示。

若基于 Valine
请参考其官方文档完成 LeanCloud 的配置，并在 params.yml 中将 valine.enable 改为 true，并填入自己的 appId 和 appKey

valine:
  enable: true
  appId: "your appId"
  appKey: "your appKey"

若基于 Waline
请参考其官方文档完成 LeanCloud 的配置，并在 params.yml 中将 waline.enable 改为 true，并填入自己的 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

若基于 twikoo
请参考其官方文档完成腾讯云或 Vercel 部署，并在 params.yml 中将 twikoo.enable 改为 true，并填入自己的 envId

twikoo:
  enable: true
  envId: # 腾讯云环境填 envId；Vercel 环境填地址（https://xxx.vercel.app）
  region:

若基于 giscus
请参考文档完成仓库的配置，并在 params.yml 中将 giscus.enable 改为 true，并填入对应的数据

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
  # commentTheme: preferred_color_scheme invalid
  lang: zh-CN

若基于 gitalk
请参考其官方文档完成仓库的配置，并在 params.yml 中将 gitalk.enable 改为 true，并填入对应的数据

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 # 是否使用 md5 加密路径

站内搜索

基于 Algolia，请在外层 hugo.toml 中添加如下配置

[outputs]
home = ["Algolia", "HTML", "RSS"]

[outputFormats.Algolia]
baseName = "algolia"
isPlainText = true
mediaType = "application/json"
notAlternative = true

这样会在 public 文件夹下生成 algolia.json 文件，用于 Algolia 搜索。接着你可以使用诸如 atomic-algolia 等插件将其上传到 Algolia

同时，在 params.yml 中将 algolia_search.enable 改为 true，并填写相关信息（注意！这里填写的是Search-Only Key，不允许填写Admin Key！！否则可能被攻击）

algolia_search:
  enable: true

数学公式

请先在外层 hugo.toml 中添加如下配置

[markup.goldmark.extensions.passthrough]
enable = true
delimiters.block = [["\\[", "\\]"], ["$$", "$$"]]
delimiters.inline = [["\\(", "\\)"], ["$", "$"]]

并在需要使用数学公式的文章的 Front matter 中添加 math 为 true

---
math: true
---

注意不要同时开启 KaTeX 和 MathJax3

KaTeX

若基于 Katex，请在 params.yml 中将 math.katex.enable 改为 true

math:
  katex:
    enable: true

MathJax3

若基于 MathJax3，请在 params.yml 中将 math.mathjax.enable 改为 true，并可在 options 中添加配置（由于 Hugo 会自动将对象的key转变为全小写，所以配置需要放在一个数组中避免默认行为）

math:
  mathjax:
    enable: true
    options: [{}]

Mermaid

流程图基于 Mermaid，请在需要使用流程图的文章的 Front matter 中添加 mermaid 为 true

---
mermaid: true
---

RSS

RSS 自带，无需额外配置

Icon

Icon 默认使用本项目提供的 iconfont

icon_font: 4552607_0khxww3tj3q9

如果想要继续使用 fontawesome 图标，请将 icon_font 设置为 false，此时会使用 vendor.yml 中对应的 fontawesome

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

扩展功能

暗黑模式

默认为 auto，根据用户系统设置自动切换。可以设置为 true 或 false 改变默认状态

dark_mode:
  # true 代表暗黑模式默认开启
  # false 代表暗黑模式默认关闭
  # auto 代表根据用户系统设置自动切换
  enable: auto # true | false | auto

Pace 进度条

默认开启

pace:
  enable: true

Firework 鼠标特效

默认开启

firework:
  enable: true

具体配置请查看 mouse-firework

PJAX

默认关闭

pjax:
  enable: false

PJAX 用于那些需要添加音乐播放器等需要 SPA 的用户。但其仍然属于实验性质，引入后可能会出现诸如脚本无法执行、脚本重复执行、页面渲染混乱等 BUG。请慎重考虑！

ServiceWorker

默认关闭

service_worker:
  enable: false

Live2D

默认关闭

live2d:
  enable: false
  position: left # left | right

Live2D Widgets

默认关闭

live2d_widgets:
  enable: false
  position: left # left | right

Reimu 鼠标指针

默认开启

reimu_cursor: true

响应式头图

默认关闭，打开后并提供对应尺寸的图片和媒体查询可以在一定程度上提高移动端的 LCP

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)"

Quicklink

默认开启，打开后可以在用户停留在页面时预加载链接，提高用户体验

quicklink:
  enable: true
  timeout: 3000 # 预加载超时时间
  priority: true # 是否优先加载
  ignores: [] # 忽略的链接，仅支持字符串

文章版权声明

默认关闭

article_copyright:
enable: false # 是否展示版权卡片？
content:
  author: # true | false 版权卡片展示作者？
  link: # true | false 版权卡片展示链接？
  title: # true | false 版权卡片展示标题？
  date: # true | false 版权卡片展示创建日期？
  updated: # true | false 版权卡片展示更新日期？
  license: # true | false 版权卡片展示协议？

此外，也可以通过文章的 front-matter 控制，其优先级高于全局配置

---
copyright: true # 是否展示版权卡片？
---

文章过期提醒

默认关闭

outdate:
  enable: false
  daysAgo: 180 # 多少天前的文章算过期
  message: 本文最后更新于 {time}，请注意文中内容可能已经发生变化。

赞助

默认关闭

sponsor:
  enable: false # 是否展示赞助二维码？
  tip: 请作者喝杯咖啡吧！ # 赞助提示
  icon:
    url: "../images/taichi.png" # 赞助图标，相对于 css/main.css 的路径，所以需要向上一级才能找到 images 文件夹
    rotate: true # 是否旋转图标
    mask: true # 是否将图片作为遮罩（即只显示 png 图片的轮廓）
  qr:
    - name: 支付宝 # 二维码名称
      src: "sponsor/alipay.jpg" # 示例二维码路径，位于 static/sponsor/aliapy.jpg

此外，也可以通过文章的 front-matter 控制，其优先级高于全局配置

---
sponsor: true # 是否展示赞助二维码？
---

音乐播放器（v0.4.0+）

使用前建议先打开 Pjax，否则会出现播放器自动暂停的问题

使用Aplayer + Meting（可选）默认关闭

纯Aplayer

将 player.aplayer.enable 设置为 true，并在 player.aplayer.options 中参考 Aplayer Docs 进行配置

player:
  aplayer:
    enable: true
    options:
      audio: [] # audio list
      fixed:
      autoplay:
      loop:
      order:
      preload: 
      volume:
      mutex:
      listFolded:
      lrcType:

Aplayer + Meting

同时将 player.aplayer.enable 和 player.meting.enable 设置为 true，并在 player.meting.options 中参考 Meting Docs 进行配置，player.aplayer.options 为 Aplayer 配置

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:

分享链接/卡片（v0.5.0+）

默认关闭，目前支持 facebook、twitter、linkedin、reddit、weibo、qq、weixin。

share:
  # - facebook
  # - twitter
  # - linkedin
  # - reddit
  # - weibo
  # - qq
  # - weixin

weixin 状态下会生成带有二维码的分享卡片，可保存到本地后分享到微信朋友圈（注意，当文章封面存在跨域问题时无法使用 html-to-image 正确生成含图片的卡片！）

首页目录卡片（v0.6.0+）

默认关闭，打开后可以在首页展示目录卡片，用于代替 widget 中的目录

home_categories:
  enable: false # 是否展示首页目录卡片？
  content:
    - categories: # 目录名称，字符串类型
      cover: # 卡片封面，不填则使用随机封面
    - categories:
      cover:

内置卡片shortcode

friendLink 友链卡片

{{< friendsLink >}}

无参数，直接读取 data/friends.yml 文件

postLinkCard 内链卡片

{{<postLinkCard path="?" cover="?" escape="?" >}}

其中第一个参数为文章的 path；第二个参数（可选）为卡片展示的封面，如果设置为 auto 则自动使用博客的 banner；第三个参数（可选，true | false）表示文章标题是否被转义

externalLinkCard 外链卡片

{{<externalLinkCard title="?" link="?" cover="?">}}

其中第一个参数为文章的标题；第二个参数为文章的外部链接，第三个参数（可选）为卡片展示的封面，如果设置为 auto 则自动使用缺省封面

自定义主题

定制主题颜色

hugo-theme-reimu 主题支持通过 CSS 变量定制主题颜色，你可以通过修改 :root 伪类下的 CSS 变量来定制你的主题颜色。

变量文件位于 assets/css/_variables.scss，你可以在这个文件中找到所有的 CSS 变量，但其实只需要修改以下伪类下的变量即可：

: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);
  }
}

自定义字体

可通过以下配置定义谷歌字体：

# https://fonts.google.com/
font:
  article:
    - Mulish
    - Noto Serif SC
  code:
    # - Ubuntu Mono
    # - Source Code Pro
    # - JetBrains Mono

v0.2.0 添加了 local_font 配置用于定义本机字体，其优先级比谷歌字体低：

local_font:
  article:
    - "-apple-system"
    - PingFang SC
    - Microsoft YaHei
    - sans-serif
  code:
    - Menlo
    - Monaco
    - Consolas
    - monospace

定制图标

头部 / 侧边栏图标

v0.1.0 的 menu 配置的结构发生了变化，允许用户自定义 icon。icon 为空时默认使用太极图标，你可以填写一个十六进制的数字来自定义 icon，同时支持 fontawesome 和 icon font。

menu:
  - name: home
    url: /
    icon: # 不填默认使用太极图标
  - name: archives
    url: /archives
    icon: f0c1 # 你可以填写一个十六进制的数字来自定义 icon，支持 fontawesome 和 icon font
  - name: about
    url: /about
    icon:
  - name: friend
    url: /friend
    icon:

底部 / 回到顶部 / 赞助图标

v0.1.0 的 footer、top、sponsor 配置均增加了 icon 配置用于自定义图标。

url 为图标的路径，相对于 css/main.css 的路径，所以需要向上一级才能找到 images 文件夹。
rotate 为是否旋转图标，默认为 true。
mask 是否将图片作为遮罩（即只显示 png 图片的轮廓），默认为 true。

footer:
  icon:
    url: "../images/taichi.png" # 相对于 css/main.css 的路径，所以需要向上一级才能找到 images 文件夹
    rotate: true
    mask: true

top:
  icon:
    url: "../images/taichi.png"
    rotate: true
    mask: true

sponsor:
  icon:
    url: "../images/taichi.png"
    rotate: true
    mask: true

加载图标

v0.1.0 的 preloader 配置增加了 icon 配置用于自定义图标。icon 为空时默认使用内链的 svg（保证首屏加载速度），你可以填入一个链接来自定义加载图标。

不建议使用过大的图标，以免影响加载速度。

preloader:
  enable: true
  text: 少女祈祷中...
  icon: # 不填默认使用内链的svg（保证首屏加载速度），你可以填入一个链接来自定义加载图标，如 '/images/taichi.png'

锚点图标

v0.1.0 增加了 anchor_icon 配置用于自定义锚点图标，默认使用 # 图标，你可以填写一个十六进制的数字来自定义 icon，同时支持 fontawesome 和 icon font。

anchor_icon: # 不填默认使用 # 图标

鼠标图标（v0.5.0+）

v0.5.0 增加了 reimu_cursor.cursor 配置用于自定义鼠标图标，你可以填写一个相对于 css/main.css 的路径来自定义鼠标图标。

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 用于存放一些第三方资源，如 fontawesome、iconfont、katex、mathjax 等。

hugo-theme-reimu 的 vendor 结构非常灵活，其支持以下几种形式：

:cdn|:package@:version/:file：使用 CDN 加速，如 cdn_jsdelivr_gh|[email protected]/dist/katex.min.css，:cdn可在 vendor 中自行配置。目前自带以下 CDN 源：

cdn_jsdelivr_gh: https://cdn.jsdelivr.net/gh/ # 仅针对github加速
cdn_jsdelivr_npm: https://cdn.jsdelivr.net/npm/ # 仅针对npm加速
fastly_jsdelivr_gh: https://fastly.jsdelivr.net/gh/ # 仅针对github加速
fastly_jsdelivr_npm: https://fastly.jsdelivr.net/npm/ # 仅针对npm加速
unpkg: https://unpkg.com/ # 仅针对npm加速
webcache: https://npm.webcache.cn/ # 仅针对npm加速

用户可根据网络状况自行切换 CDN 源。

https://:path 开头：直接使用绝对链接，如 https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css
:path 开头：本地资源，你可以把资源放在 static 文件夹下，然后使用诸如 katex.min.css 的路径引用

此外，vendor 还支持 SRI 校验，你可以在 vendor 中使用 SHA-384 用于校验资源的完整性，如：

js:
  clipboard: # 使用 SRI 校验
    src: webcache|[email protected]/dist/clipboard.min.js
    integrity: sha384-J08i8An/QeARD9ExYpvphB8BsyOj3Gh2TSh1aLINKO3L0cMSH2dN3E22zFoXEi0Q
  lazysizes: webcache|[email protected]/lazysizes.min.js # 不使用 SRI 校验

以上两种形式均支持，建议对外部 CDN 资源使用 SRI 校验，以确保资源的完整性。

许可

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github/workflows		.github/workflows
LICENSE		LICENSE
README.en.md		README.en.md
README.md		README.md
config.toml		config.toml
index.html		index.html
package.json		package.json
theme.toml		theme.toml

License

FrankGraen/frankg.github.io

Folders and files

Latest commit

History

Repository files navigation

hugo-theme-reimu

特性

基础功能

代码与数学

搜索与评论

统计与分析

媒体与交互功能

导航与结构

设计与自定义

安装

使用

创建配置

主题配置

数据配置

静态资源配置

语言配置

基本结构

archives

post

about.md

friend.md

头像、封面、头图和favicon

头像

封面

头图

Favicon

代码块

站内评论

站内搜索

数学公式

KaTeX

MathJax3

Mermaid

RSS

Icon

扩展功能

暗黑模式

Pace 进度条

Firework 鼠标特效

PJAX

ServiceWorker

Live2D

Live2D Widgets

Reimu 鼠标指针

响应式头图

Quicklink

文章版权声明

文章过期提醒

赞助

音乐播放器（v0.4.0+）

纯Aplayer

Aplayer + Meting

分享链接/卡片（v0.5.0+）

首页目录卡片（v0.6.0+）

内置卡片shortcode

friendLink 友链卡片

postLinkCard 内链卡片

externalLinkCard 外链卡片

定制主题颜色

自定义字体

定制图标

头部 / 侧边栏图标

底部 / 回到顶部 / 赞助图标

加载图标

锚点图标

鼠标图标（v0.5.0+）

Vendor

许可

About

Resources

License

Uh oh!

Stars

Watchers

Packages