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

评论系统

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

启用评论

在 hugo.yaml 中配置：

1
2

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

配置 Giscus

1. 准备工作

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

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

2. 获取配置参数

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

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

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

params:
  assets:
    chromaStyle: catppuccin-macchiato  # 代码高亮样式

可用样式列表

样式名称 说明
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

params:
  ShowCodeCopyButtons: true    # 显示代码复制按钮

代码块示例

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
3
4

params:
  ShowToc: true            # 显示目录（默认 true，不配置也会显示）
  TocOpen: true            # 目录默认展开（默认 true，不配置也会展开）
  TocPosition: auto        # 目录位置：left / right / auto

悬浮模式

1
2
3
4

params:
  tocHover: true           # 启用目录悬浮模式
  tocHoverDelay: 200       # 悬浮延迟（毫秒）
  tocHideDelay: 2000       # 隐藏延迟（毫秒）

悬浮模式说明：

  • 鼠标悬停时才显示目录
  • 点击后目录保持显示
  • 适合长文章，不占用页面空间

文章级控制

1
2
3
4
5
6
7

---
title: "文章标题"
ShowToc: true
TocOpen: true
TocPosition: left
tocHover: false
---

面包屑导航

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

SEO 优化

基本配置

1
2
3

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

搜索引擎验证

1
2
3
4
5
6

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

文章级 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：跟随系统设置