极简 Wiki：05-功能配置

本文档全面介绍极简(jijian) 主题的功能配置方法，涵盖评论系统、搜索、页脚、RSS 订阅、图片灯箱、SEO 优化等。

评论系统

极简(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: false                        # 禁用评论（默认跟随全局设置）
---

搜索功能

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

配置搜索页面

1. 添加菜单项

在 hugo.yaml 中配置：

1
2
3
4
5
6
menu:
  main:
    - identifier: search
      name: 搜索
      url: /search/
      weight: 20

2. 创建搜索页面

创建 content/search.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 配置选项

你可以通过在 content/search.md 的内容末尾添加一段脚本来定制搜索框的行为（提示：请使用 rawhtml 短代码包裹这段 HTML，以确保它能被正确渲染且不被 Markdown 解析干扰）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{{< rawhtml >}}
<script>
window.addEventListener('DOMContentLoaded', (event) => {
    new PagefindUI({
        element: "#search",
        showSubResults: true,      // 是否显示子查询结果
        showImages: false,         // 搜索结果中是否显示图片
        autofocus: true,           // 页面加载后自动聚焦搜索框
        translations: {            // 自定义界面翻译
            placeholder: "搜索文章内容...",
            zero_results: "没有找到相关结果"
        }
    });
});
</script>
{{< /rawhtml >}}

页脚配置

基本配置

在 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
10
11
params:
  footer:
    hideCopyright: false              # 隐藏版权信息
    text: "自定义页脚文字"           # 自定义页脚内容，如备案号（支持 HTML）
    badges:
      - url: "https://your-domain.com"   # 徽标链接
        badge: "https://img.shields.io/xxxx"   # 徽标图片链接
        title: "页脚徽标01"    # 徽标标题
      - url: "https://your-domain.com"
        badge: "/img/badge.svg"   # 徽标图片本地路径
        title: "页脚徽标02"

参数说明

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

徽标本地化推荐

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

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

SEO 优化

可配合极简主题丨多平台部署的SEO优化指南观看。

基本配置

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

搜索引擎验证与统计

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

站点验证标签

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
params:
  analytics:
    google:
      SiteVerificationTag: "xxxxx"
    bing:
      SiteVerificationTag: "xxxxx"
    yandex:
      SiteVerificationTag: "xxxxx"
    naver:
      SiteVerificationTag: "xxxxx"

百度统计 (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
8
---
lastmod: 2026-03-23 21:15:00  # 搜索引擎会认为你经常更新文章
title: "文章标题"
description: "文章描述"
keywords: ["关键词1", "关键词2"]
canonicalURL: "https://your-domain.com/post/article/"
robotsNoIndex: false       # 是否禁止索引
---

lastmod不仅仅是页面显示，它对 SEO 有明显的优化作用。

结构化数据 (Schema.org)：Hugo 会自动将 lastmod 填入 JSON-LD 结构化数据中的 dateModified 字段。
站点地图 (Sitemap)： Hugo 生成的 sitemap.xml 默认会使用 .Lastmod 来填充标签。
排序权重：在 posts 列表页改用了 ByLastmod 排序，这意味着你最新更新的内容会排在列表的最前面。

性能优化

图片优化

使用 WebP 格式：Hugo Extended 会自动转换
配置响应式图片：

1
2
3
params:
  cover:
    responsiveImages: true  # 默认已开启，不配置这一项也行

当你在文章中插入一张 4000 像素的高清大图时，如果不开启此功能，手机用户也必须下载完整的大图，非常耗流量且加载慢。开启后，Hugo 会在构建时自动为这张图生成 360px、480px、720px 等多个尺寸的缩略图。

注意：这要求图片存放在"文章资源包（Page Bundles）“中（即图片和文章.md文件在同一个文件夹下），或者是博客根目录下的 assets 目录下（没有可以自己新建这个文件夹）的资源。

图片压缩：使用工具压缩图片后再上传

资源指纹

1
2
3
params:
  assets:
    disableFingerprinting: false    # 默认已启用资源指纹，此处false表示不禁用，就是已启用的意思

指纹（Fingerprinting）是指在 CSS 和 JS 文件的文件名后面加一串随机的哈希字符。例如：style.css 变成 style.abcd123.css。

比如你修改了博客的颜色，重新部署：

没有指纹：读者的浏览器可能缓存了旧的 style.css，导致他看到的还是旧颜色，甚至排版错乱（除非他手动刷新）
有指纹：因为文件内容变了，生成的文件名变成了 style.wxyz456.css。浏览器发现文件名变了，会强制下载最新版

安全性 (SRI)：开启指纹后，HTML 会包含一个 integrity 校验码。如果你的 CDN 节点被黑客篡改了文件，浏览器会自动拦截，防止恶意代码运行。

构建优化

1
2
3
minify:
  disableXML: true
  minifyOutput: false  # 本地预览时选择false，部署的时候已经包含了true

懒加载

主题已内置图片懒加载，无需额外配置。

Markdown 功能（原生/扩展）

Hugo 内置了对 Markdown 的支持，此处列举两个常用的功能，其他功能请自行探索。

任务列表

完成Front Matter设置
添加短代码示例
测试所有功能

脚注

这是一个脚注示例¹。

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

主题切换

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

主题模式：

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

图片灯箱

极简(jijian) 主题内置 medium-zoom 图片缩放功能。所有文章内的图片默认支持灯箱效果，无需额外配置。

点击图片平滑放大
支持滚轮缩放
带链接的图片，点击会跳转链接，不触发灯箱

本地开发技巧

预览草稿

1
2
# 预览草稿文章
hugo server -D

预览未来日期文章

1
2
# 预览未来日期的文章
hugo server -F

这是脚注的内容。 ↩︎