极简 Wiki：06-特殊配置

封面图与顶部图

极简(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 搜索结果中依然可以显示该文章的缩略图，这能保证搜索体验不受影响。

图片素材规格推荐

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

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

文章加密

jijian 主题支持高度安全且跨平台的文章加密功能。与传统的后端验证不同，它在构建阶段对文章正文进行 AES 加密，解密过程完全在访客的浏览器本地完成。

功能特点

• 强力加密：使用 AES-256-GCM 算法，正文在服务器上以密文形式存储
• 跨平台通用：不依赖特定平台功能，任何静态托管平台均可运行
• 零依赖解密：使用浏览器原生 WebCrypto API，不加载任何外部 JS 库
• SEO 友好：加密文章会自动被 Pagefind 搜索索引忽略，保护隐私
• 优雅交互：内置极致美观的毛玻璃（Glassmorphism）解锁界面

加密方式

目录加密

只需将你的 .md 文章文件放在 content/posts/protected/ 文件夹下，该文件夹内的所有文章都会被自动标记为加密文章，构建时自动执行加密。

参数加密

在任何文章的前置参数（Front Matter）中添加以下参数之一：

1
2
3
4
5

---
title: "我的私密日记"
date: 2024-03-21
password: "123456"          # 也可以使用中文参数名：mima: "123456"
---

全局参数配置

在 hugo.yaml 中，可以统一定义加密页面的行为：

1
2
3
4
5
6
7
8

params:
  # 加密验证有效期 (秒)
  # 默认 3600 (1小时)，0 表示仅限本次访问（浏览器关闭即失效）
  authDuration: 3600

  # 自定义加密页面提示语
  # 如果不配置，系统将自动使用多语言默认值（支持 zh-cn/zh-tw/en）
  authTip: "这是一个自定义提示：本站内部资料，请输入密码观看。"

深度隐私保护：双重标题与封面

为了防止文章在未解密状态下被"窥探"标题或封面内容，主题引入了"内外双修"的机制。

realTitle (真实标题)

• 用途：列表页、搜索结果页显示一个"普通标题"，解密后显示"真实标题"
• 配置：

1
2
3
4

---
title: "一个平平无奇的标题" # 外部可见
realTitle: "这是我的秘密日记" # 解密后显示
---

realCover (真实封面)

• 用途：解密前显示占位图，解密成功后自动替换为真实的封面
• 配置：

1
2
3
4
5
6
7

---
cover:
  image: "/img/lock-placeholder.jpg" # 解密前/SEO/社交分享可见
realCover:
  image: "/img/secret-wallpaper.jpg" # 解密后瞬间替换
  caption: "这就是解锁后的惊艳画面"    # 可选，真实封面说明
---

SEO 防火墙 (搜索引擎隔离)

为了防止搜索引擎抓取到你的私密内容，主题内置了以下自动化逻辑：

自动 robots 屏蔽

只要文章被识别为"加密文章"（带密码或在 protected 目录），主题会自动在网页头部插入：

1

<meta name="robots" content="noindex, nofollow">

这意味着：

• Google/百度：不会将该页面编入搜索库
• 隐私安全：即便别人通过特定关键词搜索，也无法搜到该加密页面的任何内容

站内搜索保护 (Pagefind)

• 正文忽略：Pagefind 在索引时会完全跳过带密码的文章内容
• 搜索隔离：除非你专门在公开字段（如 summary）中泄露信息，否则用户无法通过站内搜索搜到加密文章里的任何字句

构建与加密

要使加密生效，必须运行包含加密脚本的构建命令。推荐在 package.json 中配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "name": "your-blog",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "hugo --gc --minify && node themes/jijian/assets/js/encrypt.js && npx pagefind --site public --output-path public/pagefind"
  },
  "dependencies": {
    "pagefind": "^1.4.0"
  }
}

执行 npm run build 后，脚本会自动搜索含有密码标签的文章并进行加密处理。

构建命令分解：

• hugo：构建站点
• --gc：清理未使用的资源
• --minify：压缩输出
• node .../encrypt.js：扫描并加密文章（核心步骤）
• npx pagefind：生成搜索索引

本地预览加密效果

由于加密指令是写在编译命令中的，直接运行 hugo server 可能无法看到完整的解密 UI。

推荐的本地测试步骤：

1. 执行构建：在终端运行 npm run build
2. 启动静态服务：使用任何静态服务器查看 public 目录，例如：

   1	npx serve public

3. 访问页面：通过本地服务器地址访问加密文章，即可看到完整的密码输入界面

[!IMPORTANT] 安全提醒：请务必定期备份你的原 MD 文件。由于加密是单向且客户端的，一旦你忘记了文章密码且没有源码备份，内容将无法恢复。

文章列表聚合与折叠

当你发布了一系列相关的文章（例如 Wiki、教程系列）时，文章列表可能会被这些连续的内容占据。jijian 主题提供了聚合功能，允许你将一系列文章"折叠"为列表中的一个单一条目，并直接跳转到分类（Category）页面进行阅读。

核心原理

通过在文章的前置参数（Front Matter）中使用 hiddenInList 和 link 参数：

1. hiddenInList: true：将文章从所有列表页（首页、归档、分区列表）中隐藏，但在分类页中依然可见
2. link: "/path/"：修改该文章卡片在列表页中的跳转目标

操作步骤

以 Wiki 系列文章为例：

1. 批量隐藏子文章

在你希望隐藏的所有系列文章中添加：

1

hiddenInList: true

提示：如果你将这些文章放在同一个文件夹下，可以创建一个 _index.md 并使用 cascade 块来批量设置（请注意这会改变 Hugo 的分区结构）。

2. 创建/指定一个聚合入口

选定一篇作为该系列的"封面"文章（例如 Home.md），设置如下：

1
2
3
4
5

# 确保该条目在列表中显示
hiddenInList: false

# 设置点击卡片后直接跳转到分类页（或其他页面）
link: "/categories/jijian-wiki/"

效果说明

• 首页/列表页：只会看到一个"聚合入口"卡片
• 跳转逻辑：点击卡片直接进入分类页，读者可以在分类页看到该系列的所有完整文章列表
• 分类页/标签页：为了保证内容可达性，hiddenInList 标记在这些页面无效，所有文章依然会正常列出