本文最后更新于 183 天前 ，文中信息可能已经过时。如有问题请在评论区留言。
温馨提示

2024-05-17

本站基于 Hugo-PaperMod 扩展实现的个性化功能 & 样式修改教程将会逐步开放。

简介

PaperMod-PE (Forked from Hugo-PaperMod)， 是本站基于 PaperMod 主题修改后的开源版本。

PaperMod-PE 兼容 Hugo-PaperMod (2024-05-15 前) 的功能，参考 Hugo-PaperMod Wiki。

tofuwine/PaperMod-PE

快速开始

  1. 安装 Hugo。参考文档：Hugo Docs’s - Quick Start (需要 Hugo 版本 >= v0.125.3)

  2. 创建 Hugo Site

powershell
1
2

# 将下面 MySite 替换为你的网站名
hugo new site MySite --format yml

更多命令参考：Hugo Docs’s - hugo new site command

  1. 启用 Git
powershell
1
2
3

cd MySite
git init .
git add .
  1. 安装 PaperMod-PE 主题
powershell
1

git submodule add --depth=1 https://github.com/tofuwine/PaperMod-PE.git themes/PaperMod-PE
  1. 修改 Hugo 配置文件：
yaml
1

theme: PaperMod-PE

示例工程

PaperMod-PE-Demo：https://github.com/tofuwine/PaperMod-PE-Demo

示例工程站点：https://tofuwine.github.io/PaperMod-PE-Demo/

代码块

官方文档：Syntax highlighting

PaperMod-PE 代码块扩展实现了折叠代码块，自定义标题，自定义显示语言等功能。

同时重写了代码块样式，PaperMod 的相关参数将会失效。例如，现在复制按钮是内置的，你不能通过参数 ShowCodeCopyButtons 决定显示/隐藏复制按钮。

2025-06-24 更新

现在你可以通过全局配置 codeBlockFoldMode 来指定代码块的默认折叠模式，也可配置在文章 frontmatter 来指定某一文章中的代码折叠模式。

可选的配置有如下三种：

  • false (默认): 显示代码并可在标题出手动点击来折叠代码块
  • true: 折叠代码块，仅显示标题。点击标题可展开代码块
  • disable: 禁止折叠代码块。显示代码但不能通过点击标题手动折叠代码块
yaml
hugo.yml
params:
  codeBlockFoldMode: false

标准样式

java
1
2
3
4
5
6

public class HelloHugo {

    public static void main(String[] args) {
        System.out.println("Hello Hugo!");
    }
}

代码：

markdown
1
2
3
4
5
6
7
8

```java
public class HelloHugo {

    public static void main(String[] args) {
        System.out.println("Hello Hugo!");
    }
}
```

自定义标题

java
io.github.tofuwine.main.HelloHugo.java
1
2
3
4
5
6

public class HelloHugo {

    public static void main(String[] args) {
        System.out.println("Hello Hugo!");
    }
}

代码：

markdown
1
2
3
4
5
6
7
8

```java { title="io.github.tofuwine.main.HelloHugo.java" }
public class HelloHugo {

    public static void main(String[] args) {
        System.out.println("Hello Hugo!");
    }
}
```

自定义起始行数 & 高亮指定行

如果希望在代码块中高亮显示某一行或几行 或 修改代码块显示的起始行数，你可以按如下方式：

markdown
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

```go { hl_lines="4 6 8", lineNoStart=100 }
func GetTitleFunc(style string) func(s string) string {
  switch strings.ToLower(style) {
    case "go":
      return strings.Title
    case "chicago":
      return transform.NewTitleConverter(transform.ChicagoStyle)
    default:
      return transform.NewTitleConverter(transform.APStyle)
  }
}
```

效果：

go
100
101
102
103
104
105
106
107
108
109

func GetTitleFunc(style string) func(s string) string {
  switch strings.ToLower(style) {
    case "go":
      return strings.Title
    case "chicago":
      return transform.NewTitleConverter(transform.ChicagoStyle)
    default:
      return transform.NewTitleConverter(transform.APStyle)
  }
}

其中：

  • hl_lines: 表示需要高亮的行数，你可以指定多行，用空格分隔。
    如果连续多行，可以使用 -。例如 hl_lines="4-6 8"，即高亮 4、5、6、8 行。
  • lineNoStart：表示代码块显示的起始行数

这些都是 Hugo 中定义好的属性，你可以查看官方文档获取更多内容。

折叠代码块

通过 fold 属性，你可以定义代码块是否折叠。

对于过长或不是必须展示的代码，你可设置 fold=true，那么它将默认折叠起来。

java
HelloHugo.java
1
2
3
4
5
6

public class HelloHugo {

    public static void main(String[] args) {
        System.out.println("Hello Hugo!");
    }
}

代码：

markdown
1
2
3
4
5
6
7
8

```java {title=HelloHugo.java fold=true}
public class HelloHugo {

    public static void main(String[] args) {
        System.out.println("Hello Hugo!");
    }
}
```

自定义显示语言

此方式是为了避免渲染冲突（如 mermaid，你可能需要此方式才能正确展示语言为 mermaid）。

如果希望在代码块中展示 mermaid 的代码，如果按正常 markdown 写法：

markdown
1
2
3
4
5
6
7

```mermaid
flowchart LR
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]
```

会被渲染如下：

flowchart LR
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]

你可以通过 lang 属性，修改代码如下：

markdown
1
2
3
4
5
6
7

```markdown {lang=mermaid}
flowchart LR
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]
```

来达到以下效果：

mermaid
1
2
3
4
5

flowchart LR
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]

上述方式代码高亮语法仍是 markdown。如希望高亮显示为自定义语言，需要额外添加属性 force=true，如下：

markdown
1
2
3
4
5
6
7

```markdown {lang=mermaid force=true}
flowchart LR
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]
```

赞赏

功能描述

在章末显示 <赞赏> 按钮，点击按钮后显示微信/支付宝收款码。

样式预览

可前往本文章末预览。

配置

yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

param:
   # 启用赞赏功能
   enableReward: true
   # 赞赏按钮显示字符 (可在文章 `frontmatter` 中设置)，默认为赞赏图标
   # rewardButton: 赞赏
   # 赞赏描述 (可在文章 `frontmatter` 中设置)
   rewardDescription: 如果本文对你有所帮助，可以点击上方按钮请作者喝杯咖啡！
   # 设置微信收款码图片
   WechatPay: images/wechat_pay.jpg
   # 设置支付宝收款码图片
   Alipay: images/alipay.jpg

评论

📢 攻略已发布: PaperMod 集成 Giscus 评论

功能描述

为文章添加评论区功能。PaperMod-PE 默认集成 giscus 评论功能。

配置

评论区标题 & 副标题

设置方式如下：

yaml
1
2
3
4
5
6
7

params:
   # 启用评论
   comments: true
   # 评论区标题 (可在文章 `frontmatter` 中设置)
   discussionTitle: 欢迎来到评论区
   # 评论区子标题 (可在文章 `frontmatter` 中设置)
   discussionSubtitle: 感谢您的耐心阅读！来选个表情，或者留个评论吧！

Giscus

前往 giscus.app，获取相关配置。

yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

params:
   # giscus 评论参数
   giscus:
      repo: "<your repository>"
      repoId: "<your repo id>"
      category: "Announcements"
      categoryId: "<your category id>"
      mapping: "pathname"
      strict: "0"
      reactionsEnabled: "1"
      emitMetadata: "0"
      inputPosition: "top"
      lightTheme: "light"
      darkTheme: "dark"
      lang: "zh-CN"

样式预览

前往本文底部预览评论区。

Fancybox

功能描述

启用图片灯箱预览。

配置

按如下配置启用 Fancybox 灯箱。

yaml
1
2
3

param:
   # 启用 Fancybox 灯箱
   enableFancybox: true

数学公式

功能描述

渲染数学公式，同时支持内联显示和块显示。PaperMod-PE 支持 KaTex 和 MathJax 两种渲染方式。

样式预览

内联显示

两数和的平方，等于它们的平方和加上它们的积的2倍。 即：$(a+b)2=a2+2ab+b^2$

代码：

markdown
1

两数和的平方，等于它们的平方和加上它们的积的2倍。 即：\$(a+b)^2=a^2+2ab+b^2\$

块显示

$$ \begin{aligned} KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\ JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2})) \end{aligned} $$

代码：

markdown
1
2
3
4
5
6

$$
\begin{aligned}
KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\
JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2}))
\end{aligned}
$$

更多预览，请参考：Markdown 数学公式

配置

按如下方式启用数学公式渲染：

yaml
1
2
3
4
5

params:
   # 启用数学公式渲染
   enableMath: true
   # 数学公式渲染方式: `katex` or `mathjax`
   mathematicsRenderer: mathjax

悬浮按钮

PaperMod-PE 支持三种悬浮按钮：回到顶部 (Go to Top)、前往评论区 (Go to Comment)、切换主题 (Theme toggle)。 你可以在屏幕右下角体验这些悬浮按钮。

前往评论区 (Go to comment)

功能描述

快速跳转到评论区。

配置

yaml
1
2
3

params:
   # 悬浮按钮 —— Go to Comment
   enableScrollToComment: true

切换主题 (Theme toggle)

功能描述

切换页面主题 (light / dark)。

配置

yaml
1
2
3

params:
   # 悬浮按钮 —— Theme Toggle
   enableThemeToggleFloat: true

回到顶部 (Go to top)

功能描述

快速跳转到页面顶部。

配置

yaml
1
2
3

params:
   # 悬浮按钮 —— Go to Top
   enableScrollToTop: true

文章版权声明

📢 攻略已发布: PaperMod 添加文章版权声明

在章末显示原创内容版权信息 or 转载内容的原文信息。

原创内容

可为原创内容显示版权信息，同时显示文章标题(含作者名) & 文章链接。

配置

可通过 config.yml 配置默认 license 信息：

yaml
1
2
3
4
5
6
7

params:
   # 文章作者 (PaperMod 主题参数)
   author: tofuwine
   # 版本链接
   licenseLink: "https://creativecommons.org/licenses/by-nc/4.0/"
   # 版本显示名
   licenseName: "CC BY-NC 4.0"

也可在文章 frontmatter 中指定 license 信息：

markdown
1
2
3
4
5

---
author: tofuwine
licenseLink: "https://creativecommons.org/licenses/by-nc/4.0/"
licenseName: "CC BY-NC 4.0"
---

样式预览

你可以在本文章末预览样式。

转载内容

为转载内容显示原文标题、作者、链接以及侵权联系方式。

配置

在 frontmatter 中添加如下配置：

markdown
1
2
3
4
5
6
7

---
reposted: true
repostedTitle: "PaperMod-PE Documents"
repostedAuthor: "tofuwine"
repostedLink: "https://www.tofuwine.cn/articles/site/hugo/041e0ff6-f9a1-4212-a1de-5af6c2c7568a/"
contactEmail: tofuwine@outlook.com
---

其中联系方式也可在 config.yml 进行全局配置：

yaml
1
2

params:
   contactEmail: tofuwine@outlook.com

样式预览

前往转载文章 Linux 文件系统的组成 的章末预览样式。

TypeIt

主页副标题使用 TypeIt 动态效果。hugo 配置文件增加如下配置：

yaml
1
2

params:
   enableTypeIt: true

说明：当前仅支持主页副标题，其他页面无效果。

Cloudflare Web Analytics

通过以下配置开启 Cloudflare Web Analytics 的支持：

yaml
1
2
3
4

params:
  analytics:
     cloudflare:
        WebAnalyticsToken: "your_token"

Token 获取方式：

  1. 前往 Cloudflare Dashboard
  2. 找到 分析和日志 > Web Analytics，添加你的站点会获得一个 JS 片段，拿到其中的 token 值。

如果使用 Cloudflare Pages 部署，可在你的 Pages 管理界面 管理 > Web Analytics 启用 Cloudflare Web Analytics，而无需进行上述配置。

Baidu Site Verification (Preview)

预览功能。
本站部署在 Cloudflare Pages & Github Pages，两者均已屏蔽百度爬取，无法测试。

通过以下配置添加百度网站验证：

yaml
1
2
3
4

params:
   analytics:
      baidu:
         SiteVerificationTag: "your_tag"

自定义页面

友链

  1. 添加 <友链> 页面

  2. 创建 friend.md 文件，内容参考如下：

markdown
content/friend.md
 1
 2
 3
 4
 5
 6
 7
 8
 9
10

title: "🤝 友链"
layout: "friend"
hideMeta: true
showBreadCrumbs: false
ShowToc: false
discussionTitle: 👇 申请友链 👇
discussionSubtitle: 在下方评论区留下你的链接吧!
hideRewardSubtitle: true
rewardButton: 赞
searchHidden: true

友链页面链接：/friend/

  1. 添加友链信息

通过 Shortcode friend 进行友链的添加，在 friend.md 中添加如下内容，即可添加一条友链信息。

markdown
1

{{< friend name="Tofuwine's Blog" url="https://www.tofuwine.cn" logo="https://www.tofuwine.cn/images/profile.png" description="记录、 分享，仅此。" >}}

关于

创建 about.md 文件，内容参考如下：

markdown
content/about.md
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

---
title: "🧑‍💻 关于"
layout: "about"
hideMeta: true
showBreadCrumbs: false
ShowToc: false
comments: true
discussionTitle: 👇 畅所欲言 👇
discussionSubtitle:
hideRewardSubtitle: true
rewardButton: 赞
searchHidden: true
---

关于页面链接：/about/

瞬间

📢 攻略已发布: Hugo 添加瞬间页

创建 moments/_index.md 文件，内容参考如下：

markdown
content/moments/_index.md
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

---
title: "🌟 瞬间"
layout: "moments"
DateFormat: 2006-01-02 03:04
build:
  render: always
cascade:
  - build:
      list: local
      publishResources: false
      render: never
---

瞬间页面链接：/moments/。

Shortcode

admonition

note

样式：

note
admonition - note

代码：

markdown
1
2
3

{{< admonition type=note title=note open=true >}}
admonition - note
{{< /admonition >}}

abstract

样式：

abstract
admonition - abstract

代码：

markdown
1
2
3

{{< admonition type=abstract title=abstract open=true >}}
admonition - abstract
{{< /admonition >}}

info

样式：

info
admonition - info

代码：

markdown
1
2
3

{{< admonition type=info title=info open=true >}}
admonition - info
{{< /admonition >}}

tip

样式：

tip
admonition - tip

代码：

markdown
1
2
3

{{< admonition type=tip title=tip open=true >}}
admonition - tip
{{< /admonition >}}

success

样式：

success
admonition - success

代码：

markdown
1
2
3

{{< admonition type=success title=success open=true >}}
admonition - success
{{< /admonition >}}

question

样式：

question
admonition - question

代码：

markdown
1
2
3

{{< admonition type=question title=question open=true >}}
admonition - question
{{< /admonition >}}

warning

样式：

warning
admonition - warning

代码：

markdown
1
2
3

{{< admonition type=warning title=warning open=true >}}
admonition - warning
{{< /admonition >}}

failure

样式：

failure
admonition - failure

代码：

markdown
1
2
3

{{< admonition type=failure title=failure open=true >}}
admonition - failure
{{< /admonition >}}

danger

样式：

danger
admonition - danger

代码：

markdown
1
2
3

{{< admonition type=danger title=danger open=true >}}
admonition - danger
{{< /admonition >}}

bug

样式：

bug
admonition - bug

代码：

markdown
1
2
3

{{< admonition type=bug title=bug open=true >}}
admonition - bug
{{< /admonition >}}

example

样式：

example
admonition - example

代码：

markdown
1
2
3

{{< admonition type=example title=example open=true >}}
admonition - example
{{< /admonition >}}

quote

样式：

quote
admonition - quote

代码：

markdown
1
2
3

{{< admonition type=quote title=quote open=true >}}
admonition - quote
{{< /admonition >}}

hl (Deprecated)

Deprecated：未来将会删除。

hugo 0.126.0 起支持 inserted text, mark text, subscript, and superscript。
查看官网介绍：extras-extension

文本高亮。

样式：

This is a highlight text.

代码：

markdown
1
2
3

{{< hl >}}
This is a highlight text.
{{< /hl >}}

git (Preview)

显示 git 代码仓库。

语法：(以 Gitee 平台的 dromara/hutool 仓库为例)

markdown
1

{{< git platform="gitee" repo="dromara/hutool" >}}

更方便写法：

markdown
1

{{< git "https://gitee.com/dromara/hutool" >}}

目前支持的平台：

  • github
  • gitee

GitHub

Shortcode：

markdown
1

{{< git platform="github" repo="dromara/hutool" >}}

渲染结果：

dromara/hutool

Gitee

Shortcode：

markdown
1

{{< git platform="gitee" repo="dromara/hutool" >}}

渲染结果：

dromara/hutool

特别说明

  1. 这是作者参考 halo 插件 Vditor 编辑器 实现的。目前为预览功能，仍可能存在问题。
  2. 为缓存避免频繁请求 API 接口，初次请求结果会缓存在 localStorage 中，有效期 1 小时（过期并不会删除）。
  3. 未完善异常处理。因网络等原因导致请求失败后，可能会导致样式问题。 (2024.05.20 起 支持异常样式)。

tip (Preview)

用于替代 admonition 的简码。目前支持以下类型：

default

markdown
1
2
3

{{< tip >}}
tip content
{{< /tip >}}

效果如下：

tip content

warning

markdown
1
2
3

{{< tip warning >}}
warning content
{{< /tip >}}

效果如下：

warning content

ai (Preview)

预览功能。功能及样式待完善。

引用 AI 生成的内容。

markdown
1
2
3

{{< ai >}}
这是一段由 AI 生成的内容。
{{< /ai >}}

效果如下：

这是一段由 AI 生成的内容。
Powered by AI

也可以输入 ai 平台来显示特定的名称：

平台 (输入)显示 (输出)
chatgptChatGPT
openaiChatGPT
bingMicrosoft Copilot
microsoftMicrosoft Copilot
googleGemini
alibaba通义千问
默认(除以上平台外)AI

示例：

markdown
1
2
3

{{< ai chatgpt >}}
这是一段由 ChatGPT 生成的内容。
{{< /ai >}}
这是一段由 ChatGPT 生成的内容。
Powered by ChatGPT

badge (Preview)

预览功能。功能及样式待完善。

徽章。shields.io 类似效果。

PaperMod-PE v1.0.4 badge Preview

语法如下：

markdown
1

{{< badge "PaperMod-PE" "v1.0.4" >}}

color

改变文本颜色。

效果如下：

普通字 红色的字 绿色的字

markdown
1
2
3

普通字
{{< color red >}}红色的字{{< /color >}}
{{< color "#00ff00" >}}绿色的字{{< /color >}}

可直接使用颜色名，如 red、yellow 等，也可使用十六进制，如 #00ff00。不支持 rgb(x,y,z)。

gist

此简码暂不支持 dark 主题。
2024-07-02 已适配 dark 主题

优化 Hugo 内置简码 gist。

原 gist 语法：

markdown
1

{{< gist "jmooring" "23932424365401ffa5e9d9810102a477" "list.html" >}}

新增语法：

markdown
1

{{< gist "jmooring/23932424365401ffa5e9d9810102a477#list.html" >}}

效果如下：

FAQ

如何更新主题

使用如下命令更新主题：

powershell
1

git submodule update --init --recursive