PaperMod-PE Documents

温馨提示

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

快速开始

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

powershell

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

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

启用 Git

powershell

1
2
3
cd MySite
git init .
git add .

安装 PaperMod-PE 主题

powershell

1
git submodule add --depth=1 https://github.com/tofuwine/PaperMod-PE.git themes/PaperMod-PE

修改 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)
  }
}
```

效果：

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=a^2+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 获取方式：

前往 Cloudflare Dashboard
找到 分析和日志 > 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"

自定义页面

友链

添加 <友链> 页面
创建 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/

添加友链信息

通过 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

特别说明

这是作者参考 halo 插件 Vditor 编辑器实现的。目前为预览功能，仍可能存在问题。
为缓存避免频繁请求 API 接口，初次请求结果会缓存在 localStorage 中，有效期 1 小时（过期并不会删除）。
~~未完善异常处理。因网络等原因导致请求失败后，可能会导致样式问题。~~ (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 生成的内容。

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

平台 (输入)	显示 (输出)
chatgpt	ChatGPT
openai	ChatGPT
bing	Microsoft Copilot
microsoft	Microsoft Copilot
google	Gemini
alibaba	通义千问
默认(除以上平台外)	AI

示例：

markdown

1
2
3
{{< ai chatgpt >}}
这是一段由 ChatGPT 生成的内容。
{{< /ai >}}

这是一段由 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

简介#

快速开始#

示例工程#

代码块#

标准样式#

自定义标题#

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

折叠代码块#

自定义显示语言#

赞赏#

功能描述#

样式预览#

配置#

评论#

功能描述#

配置#

评论区标题 & 副标题#

Giscus#

样式预览#

Fancybox#

功能描述#

配置#

数学公式#

功能描述#

样式预览#

内联显示#

块显示#

配置#

悬浮按钮#

前往评论区 (Go to comment)#

功能描述#

配置#

切换主题 (Theme toggle)#

功能描述#

配置#

回到顶部 (Go to top)#

功能描述#

配置#

文章版权声明#

原创内容#

配置#

样式预览#

转载内容#

配置#

样式预览#

TypeIt#

Cloudflare Web Analytics#

Baidu Site Verification (Preview)#

自定义页面#

友链#

关于#

瞬间#

Shortcode#

admonition#

note#

abstract#

info#

tip#

success#

question#

warning#

failure#

danger#

bug#

example#

quote#

hl (Deprecated)#

git (Preview)#

GitHub#

Gitee#

特别说明#

tip (Preview)#

default#

warning#

ai (Preview)#

badge (Preview)#

color#

gist#

FAQ#

如何更新主题#

简介

快速开始

示例工程

代码块

标准样式

自定义标题

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

折叠代码块

自定义显示语言

赞赏

功能描述

样式预览

配置

评论

功能描述

配置

评论区标题 & 副标题

Giscus

样式预览

Fancybox

功能描述

配置

数学公式

功能描述

样式预览

内联显示

块显示

配置

悬浮按钮

前往评论区 (Go to comment)

功能描述

配置

切换主题 (Theme toggle)

功能描述

配置

回到顶部 (Go to top)

功能描述

配置

文章版权声明

原创内容

配置

样式预览

转载内容

配置

样式预览

TypeIt

Cloudflare Web Analytics

Baidu Site Verification (Preview)

自定义页面

友链

关于

瞬间

Shortcode

admonition

note

abstract

info

tip

success

question

warning

failure

danger

bug

example

quote

hl (Deprecated)

git (Preview)

GitHub

Gitee

特别说明

tip (Preview)

default

warning

ai (Preview)

badge (Preview)

color

gist

FAQ

如何更新主题