极简（jijian）主题 Wiki：06-功能配置

本文档详细介绍 jijian 主题的各项功能配置方法，包含评论系统、搜索功能、代码高亮、社交图标、图片灯箱等。

评论系统

jijian 主题支持 Giscus 评论系统，基于 GitHub Discussions 实现。

启用评论

在 hugo.yaml 中配置：

1
2


params:
  comments: true                      # 全局启用评论

配置 Giscus

1. 准备工作

确保你的 GitHub 仓库满足以下条件：

仓库是公开的（Public）
已启用 Discussions 功能
已安装 giscus app

2. 获取配置参数

访问 giscus.app ，按照向导配置：

输入仓库地址
选择页面与 Discussions 映射方式（推荐 pathname）
选择 Discussion 分类（推荐 Announcements）
复制生成的配置参数

3. 添加配置

将获取的参数添加到 hugo.yaml：

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


params:
  comments: true
  
  giscus:
    repo: "user/repo"                 # 仓库名称
    repoId: "R_xxxxx"                 # 仓库 ID
    category: "Announcements"         # Discussion 分类
    categoryId: "DIC_xxxxx"           # 分类 ID
    mapping: pathname                 # 映射方式
    reactionsEnabled: 1               # 启用反应
    emitMetadata: 0                   # 发送元数据
    inputPosition: top                # 输入框位置：top / bottom
    theme: preferred_color_scheme     # 主题
    lang: zh-CN                       # 语言

文章级控制

在文章的 Front Matter 中可以单独控制：

1
2
3
4


---
title: "文章标题"
comments: true                        # 启用评论（默认跟随全局设置）
---

或禁用特定文章的评论：

1
2
3
4


---
title: "文章标题"
comments: false                       # 禁用评论
---

搜索功能

jijian 主题使用 Pagefind 作为搜索引擎，提供高性能的全文搜索体验。

配置搜索页面

1. 添加菜单项

在 hugo.yaml 中配置：

1
2
3
4
5
6


menu:
  main:
    - identifier: search
      name: 搜索
      url: /search/
      weight: 20

2. 创建搜索页面

创建 content/search/_index.md：

1
2
3
4


---
title: "搜索"
layout: "search"
---

构建搜索索引

Pagefind 需要在 Hugo 构建后运行，生成搜索索引。

本地开发预览

场景一：边开发边测试（推荐）

1
2
3
4
5


# 构建站点并生成索引到 static 目录
hugo && npx pagefind --site public --output-path static/pagefind

# 启动开发服务器
hugo server

注意：修改文章后需要重新运行第一条命令更新索引。

场景二：预览最终构建文件

1
2
3
4
5


# 构建站点并生成索引
hugo && npx pagefind --site public

# 使用 Pagefind 自带服务器预览
npx pagefind --site public --serve

Vercel 自动化部署

在 Vercel 构建命令中添加索引生成：

Build Command：

1

hugo --gc --minify && npx pagefind --site public --output-path public/pagefind

package.json（可选）：

1
2
3
4
5
6
7
8


{
  "name": "your-blog",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "pagefind": "^1.4.0"
  }
}

Pagefind 配置选项

搜索页支持自定义配置：

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


<script>
new PagefindUI({
    element: "#search",
    showSubResults: true,      // 显示子结果
    showImages: false,         // 不显示图片
    autofocus: true,           // 自动聚焦
    translations: {            // 翻译
        placeholder: "搜索文章...",
        zero_results: "没有找到结果"
    }
});
</script>

代码高亮

jijian 主题内置 13 款 Chroma 语法高亮样式。

选择高亮样式

在 hugo.yaml 中配置：

1
2
3
4


params:
  code:
    chromaStyle: catppuccin-macchiato  # 代码高亮样式
    showCopyButtons: true              # 显示代码块复制按钮

可用样式列表

样式名称	说明
`catppuccin-macchiato`	默认样式，与主题配色协调
`catppuccin-mocha`	Catppuccin 深色变体
`catppuccin-frappe`	Catppuccin 中等深度
`catppuccin-latte`	Catppuccin 浅色版本
`github`	GitHub 浅色风格
`github-dark`	GitHub 深色风格
`monokai`	经典 Monokai 配色
`dracula`	Dracula 主题配色
`nord`	Nord 极光配色
`tokyonight-night`	Tokyo Night 深色
`gruvbox`	Gruvbox 复古配色
`onedark`	Atom OneDark 风格
`solarized-dark`	Solarized 深色

显示行号

1
2
3
4


markup:
  highlight:
    lineNos: true              # 显示行号
    noClasses: false           # 必须为 false，主题使用 CSS 类名

代码块示例

1
2
3
4


```python
def hello():
    print("Hello, World!")
```

显示效果（带行号和复制按钮）：

1
2


1: def hello():
2:     print("Hello, World!")

社交图标

jijian 主题支持丰富的社交图标，包括国内外主流平台。

基本配置

1
2
3
4
5
6


params:
  socialIcons:
    - name: github
      url: https://github.com/yourname
    - name: bilibili
      url: https://space.bilibili.com/xxxxxx

悬浮二维码功能

配置 hoverImage 参数后，鼠标悬停在图标上会弹出图片/二维码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


params:
  socialIcons:
    - name: bilibili
      url: https://space.bilibili.com/xxxxxx
      hoverImage: /img/bilibili-qr.png
      title: 哔哩哔哩
    - name: wechat
      url: "javascript:void(0);"    # 无跳转链接
      hoverImage: /img/wechat-qr.png
      title: 微信二维码

支持的平台

国内平台

name	平台
`bilibili`	哔哩哔哩
`douyin`	抖音
`xiaohongshu`	小红书
`shipinhao`	视频号
`zhihu`	知乎
`douban`	豆瓣
`weibo`	微博
`wechat`	微信

国际平台

name	平台
`github`	GitHub
`twitter` / `x`	Twitter/X
`linkedin`	LinkedIn
`youtube`	YouTube
`instagram`	Instagram
`facebook`	Facebook
`email`	邮箱
`rss`	RSS

参数说明

参数	类型	必需	说明
`name`	string	是	平台名称
`url`	string	是	链接地址
`title`	string	否	鼠标悬停显示的文字
`hoverImage`	string	否	悬浮图片路径

图片路径说明

悬浮二维码图片应放在 static/img/ 目录下：

your-site/
├── static/
│   └── img/
│       ├── wechat-qr.png
│       ├── bilibili-qr.png
│       └── douyin-qr.png

配置时使用绝对路径：

1

hoverImage: /img/wechat-qr.png

分享按钮

文章页支持社交分享按钮。

启用分享

1
2


params:
  ShowShareButtons: true

配置分享平台

1
2
3
4
5
6
7
8
9


params:
  ShareButtons:
    - x                  # Twitter/X
    - linkedin           # LinkedIn
    - reddit             # Reddit
    - facebook           # Facebook
    - whatsapp           # WhatsApp
    - telegram           # Telegram
    - ycombinator        # Hacker News

文章级控制

在文章的 Front Matter 中可以禁用分享：

1
2
3
4


---
title: "文章标题"
disableShare: true       # 禁用分享按钮
---

图片灯箱

jijian 主题内置 medium-zoom 图片缩放功能。

功能特点

点击图片平滑放大
支持滚轮缩放
背景色自动适配主题
智能过滤带链接的图片

自动启用

所有文章内的图片默认支持灯箱效果，无需额外配置。

跳过灯箱

如果图片设置了链接（使用 figure 短代码的 link 参数），点击会跳转链接，不触发灯箱：

1
2
3
4
5


{{< figure 
  src="/images/photo.jpg"
  link="https://example.com"
  alt="点击跳转外部链接"
>}}

文章元信息

显示控制

1
2
3
4


params:
  ShowReadingTime: true    # 显示阅读时长
  ShowWordCount: true      # 显示字数统计
  readingSpeed: 200        # 阅读速度（字/分钟）

中文优化

主题针对中文进行了优化：

精确统计汉字、标点、字母、数字
基于字数计算阅读时长
支持自定义阅读速度

文章级控制

1
2
3
4
5
6


---
title: "文章标题"
ShowReadingTime: false     # 隐藏阅读时长
ShowWordCount: false       # 隐藏字数统计
hideMeta: true             # 隐藏所有元信息
---

面包屑导航

1
2


params:
  ShowBreadCrumbs: true    # 显示面包屑导航

面包屑导航显示当前页面在站点结构中的位置：

首页 > 文章 > 技术分享 > 当前文章

上下篇导航

1
2


params:
  ShowPostNavLinks: true   # 显示上下篇导航

文章级控制

1
2
3
4


---
title: "文章标题"
ShowPostNavLinks: false    # 隐藏上下篇导航
---

编辑文章链接

1
2
3
4
5
6


params:
  editPost:
    URL: "https://github.com/user/repo/tree/main/content"
    Text: "编辑"           # 按钮文字
    appendFilePath: true   # 追加文件路径
    disabled: false        # 禁用编辑按钮

完整链接示例：

https://github.com/user/repo/tree/main/content/posts/my-article.md

RSS 订阅

输出配置

1
2
3
4


outputs:
  home:
    - HTML
    - RSS

显示 RSS 按钮

1
2


params:
  ShowRssButtonInSectionTermList: true

RSS 路径

全站 RSS：/index.xml
分类 RSS：/categories/分类名/index.xml
标签 RSS：/tags/标签名/index.xml

页脚配置

基本配置

在 hugo.yaml 中配置：

1
2
3


params:
  footer:
    text: "[粤ICP备xxxxxx号](https://beian.miit.gov.cn/)" # 页脚支持 Markdown 文本

页脚徽标 (Badges/Shields)

你可以在页脚文字上方显示一行精美的徽标（建议使用 Shields.io 生成）。

配置示例

1
2
3
4
5
6
7
8
9


params:
  footer:
    badges:
      - url: "https://your-domain-1.com/"
        badge: "https://img.shields.io/badge/your_domain_1-you_like-blue"
        title: "your-domain-1阿巴阿巴阿巴"
      - url: "https://your-domain-2.com/"
        badge: "https://img.shields.io/badge/your_domain_2-you_like-blue"
        title: "your-domain-2阿巴阿巴阿巴"

参数说明

参数	说明
`url`	点击徽标后的跳转链接
`badge`	徽标图片地址。支持 Shields.io 远程 URL 或本地路径（如 `/badges/cdn.svg`）
`title`	鼠标悬停在徽标上时显示的文字提示

徽标本地化推荐

为了提高加载速度并脱离第三方服务依赖，你可以将生成的徽标 SVG 下载并存放在 static 目录中：

下载 SVG 到 static/badges/myshield.svg。
配置时将 badge 参数设为本地路径：badge: "/badges/myshield.svg"。

图片与封面配置

jijian 主题引入了双层图片系统，分别处理外部分享和内部展示。

全局配置

在 hugo.yaml 中配置：

1
2
3
4
5
6
7
8
9


params:
  # 社交分享预览图 (OpenGraph / X Cards)
  shareImages: ["/img/share.png"]
  
  # 站点默认封面图 (用于列表悬浮预览、搜索缩略图)
  defaultImage: "/img/default-cover.png"

  cover:
    displayDefault: false  # 是否默认在文章顶部显示保底图 (默认 false)

封面图可见性控制

默认情况下，封面图会在文章列表（悬浮预览）和文章详情页顶部（全景横幅）显示。

但是，如果你没有为每一篇文章都准备专门的封面图，全局设置的 defaultImage 可能会导致所有文章顶部都显示同一张图，显得冗余。

你可以通过以下方式灵活控制具体文章及全局的封面显示：

全局控制：是否显示保底图

如果你只想让默认图片显示在列表悬浮窗和搜索结果中，而不在文章内容顶部显示，请在全局配置中保持 displayDefault: false：

1
2
3


params:
  cover:
    displayDefault: false  # 默认不显示，仅用于悬浮和搜索

如果你希望即便文章未设置封面，也让默认图充当顶部的 Banner，则将其设为 true。

文章级控制：隐藏封面

如果你希望彻底隐藏某篇文章的封面，无论是否有默认值，都可以在文章 Front Matter 中设置：

1
2
3
4
5


---
cover:
  hidden: true        # 彻底隐藏（列表预览和文章内都不显示）
  hiddenInSingle: true # 仅在文章内隐藏（列表预览仍保留）
---

提示：即使配置了 hidden: true，只要设置了 defaultImage 或自定义了 cover.image，Pagefind 搜索结果中依然可以显示该文章的缩略图，这能保证搜索体验不受影响。

图片素材规格推荐

为了保证主题视觉效果的最佳呈现，建议按照以下规格准备图片素材：

素材类型	推荐比例	推荐尺寸 (像素)	说明
头像 (Avatar)	`1:1` (正方形)	`240 x 240`	用于 Card Mode 首页，建议使用 Retina 倍率以保证清晰度
分享图 (shareImages)	`1.91:1`	`1200 x 630`	国际主流社交平台 (OpenGraph) 的标准比例
文章封面 (Cover)	`16:9` 或 `32:9`	`1920 x 1080` (及以上)	文章页顶部会自动裁剪为 32:9 的超宽视野。建议主体内容居中。
站点 Logo	横向长矩形	高度固定 `32px`	建议使用 SVG 格式，以获得在任何缩放倍率下的极致清晰度
Favicon	`1:1`	`32 x 32` / `180 x 180`	提供 .ico 和 .png 两种格式的最佳适配

关于文章封面的特别说明： jijian 主题在文章详情页采用了“电影全景式” Banner 设计（比例为 32:9）。如果你上传的是标准的 16:9 图片，主题会自动保留图片的中间部分。因此在构图时，请尽量将图片的视觉重心（主体人物或文字）放在垂直正中心，以防被切掉。

SEO 优化

基本配置

1
2
3


params:
  description: "站点描述"
  keywords: ["关键词1", "关键词2"]

搜索引擎验证与统计

支持 Google、Bing、Yandex、Naver 的站点验证标签，以及百度统计。

1. 站点验证标签

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


params:
  analytics:
    google:
      SiteVerificationTag: "xxxxx"
    bing:
      SiteVerificationTag: "xxxxx"
    yandex:
      SiteVerificationTag: "xxxxx"
    naver:
      SiteVerificationTag: "xxxxx"

2. 百度统计 (Baidu Analytics)

支持在站点中集成百度统计脚本。

1
2
3
4


params:
  analytics:
    baidu:
      hm: "你的百度统计ID"  # 脚本链接 hm.js? 后的 ID 字符串

对于多域名的博客，每个域名都需要单独配置百度统计。因此可以使用环境变量的形式来配置：HUGO_PARAMS_ANALYTICS_BAIDU_HM = 你的百度统计ID

文章级 SEO

1
2
3
4
5
6
7


---
title: "文章标题"
description: "文章描述"
keywords: ["关键词1", "关键词2"]
canonicalURL: "https://your-domain.com/post/article/"
robotsNoIndex: false       # 是否禁止索引
---

主题切换

1
2
3


params:
  defaultTheme: auto              # 默认主题：light / dark / auto
  disableThemeToggle: false       # 禁用主题切换按钮

主题模式：

light：浅色主题
dark：深色主题
auto：跟随系统设置

评论系统

启用评论

配置 Giscus

1. 准备工作

2. 获取配置参数

3. 添加配置

文章级控制

搜索功能

配置搜索页面

1. 添加菜单项

2. 创建搜索页面

构建搜索索引

本地开发预览

Vercel 自动化部署

Pagefind 配置选项

代码高亮

选择高亮样式

可用样式列表

显示行号

代码块示例

社交图标

基本配置

悬浮二维码功能

支持的平台

国内平台

国际平台

参数说明

图片路径说明

分享按钮

启用分享

配置分享平台

文章级控制

图片灯箱

功能特点

自动启用

跳过灯箱

文章元信息

显示控制

中文优化

文章级控制

目录

基本配置

悬浮模式

文章级控制

面包屑导航

上下篇导航

文章级控制

编辑文章链接

RSS 订阅

输出配置

显示 RSS 按钮

RSS 路径

页脚配置

基本配置

页脚徽标 (Badges/Shields)

配置示例

参数说明

徽标本地化推荐

图片与封面配置

全局配置

封面图可见性控制

全局控制：是否显示保底图

文章级控制：隐藏封面

图片素材规格推荐

SEO 优化

基本配置

搜索引擎验证与统计

1. 站点验证标签

2. 百度统计 (Baidu Analytics)

文章级 SEO

主题切换