布局与页面功能完整教程与测试

本文既是 matery 主题布局与页面功能的完整使用教程，也是 自动化测试靶场。覆盖：文章布局特性、侧边栏组件、响应式断点、相册、搜索、评论、暗色模式、加密、RSS/站点地图、PWA。自动化测试（tools/tests/release-test.sh）会断言下方标注的渲染标记。

1. 文章布局特性

1.1 上下篇导航（上一篇/下一篇）

用途：文章底部展示上一篇/下一篇卡片，引导读者连续阅读。

配置（主题 _config.yml）：

# 文章底部上下篇导航（自动按时间排序相邻文章）
prenext:
  enable: true

实现效果：文章末尾左右两张卡片，显示相邻文章标题 + 缩略图，hover 有渐变背景。

测试断言：文章页含 #prenext-posts 容器。

1.2 版权声明

用途：文章底部展示版权/许可协议，注明作者与转载规则。

配置（主题 _config.yml）：

post:
  copyright: true          # 显示版权声明
  license: 本文采用 CC BY-NC-SA 4.0 许可协议

实现效果：文章底部灰色版权卡片，含作者、链接、许可协议三行。

测试断言：文章页含版权声明容器（#copyright 或 .post-copyright）。

1.3 文章时效提示

用途：对过期文章显示"内容可能已过时"提示，按天数分级（警告/错误样式）。

配置（主题 _config.yml）：

post:
  outdate:
    enable: true
    warning_day: 365      # 超过 365 天显示警告样式 note
    error_day: 3650       # 超过 3650 天显示错误样式 note

实现效果：文章开头显示过期提示 note，天数越长样式越醒目。

测试断言：文章页含时效提示元素（outdate 相关 class）。

1.4 TOC 目录

用途：右侧（或侧边栏）显示文章章节导航，点击跳转对应标题，滚动高亮当前章节。

配置（主题 _config.yml）：

# TOC 目录
toc:
  enable: true
  # 锚点偏移（配合固定导航栏）
  anchor_offset: 60

实现效果：桌面端右侧悬浮目录树，随滚动高亮当前标题；移动端折叠进侧边栏。

测试断言：文章页含 #toc-content 目录容器。

1.5 广告位

用途：TOC 下方预留广告位（卡片形式）。

配置：广告卡片由 _partial/side-bar-ad.ejs 渲染，内容在模板中维护。

实现效果：侧边栏 TOC 下方展示广告卡片（.tgCard）。

测试断言：文章页含 .tgCard 广告容器。

2. 侧边栏组件（widgets）

2.1 分类雷达图

用途：/categories/ 页面用 canvas 雷达图展示各分类文章数量分布。

实现效果：分类页顶部 canvas 雷达图，每个分类一个维度。

测试断言：/categories/ 含 <canvas> 元素。

2.2 标签云

用途：/tags/ 页面以 chip 样式展示全部标签，点击跳转对应标签页。

实现效果：标签页彩色圆角 chip，hover 高亮。

测试断言：/tags/ 含 .tag-chips .chip。

2.3 词云

用途：/tags/ 页面 canvas 词云，标签大小/颜色按权重分布。

实现效果：标签页 canvas 词云（字号 ∝ 文章数）。

测试断言：/tags/ 含词云 canvas 容器。

2.4 归档时间线

用途：/archives/ 页面按年/月时间线归档全部文章。

实现效果：垂直时间线，圆点 + 年份折叠。

测试断言：/archives/ 含 #cd-timeline。

2.5 关于页统计

用途：/about/ 页面用多张图表展示站点统计（文章数/分类/标签/时间线等）。

实现效果：关于页多组 canvas 图表。

测试断言：/about/ 含多个 <canvas> 元素。

3. 响应式断点

配置（themes/matery/source/css/_variables/base.styl）

$breakpoint-sm: 368px   // 超小屏（手机竖屏）
$breakpoint-md: 768px   // 平板/手机横屏
$breakpoint-lg: 992px   // 桌面
$breakpoint-fun: 1400px // 特效启用阈值（大屏）

各断点布局

实现效果

Bootstrap/Materialize 栅格自适应，侧边栏在窄屏自动隐藏，TOC 移动端折叠。

测试断言：<768px 导航折叠；>992px 桌面三栏；>1400px 特效启用。

4. 相册功能

数据源（source/_data/galleries.yml）

相册名:
  photos: 单张图对象 | 字符串路径 | 目录路径  # 三种形式
  cover: 封面图
  description: 描述

页面结构

• /galleries/ — 相册列表页（卡片 + 封面）
• /galleries/<名称>/ — 单个相册页（灯箱 + caption）
• 加密相册：front-matter 加 password，进入需解密

实现效果

列表卡片 + 内页 lightGallery 灯箱浏览，加密相册解密后显示。

测试断言：

• /galleries/ 相册列表
• /galleries/2020/ 灯箱 + caption
• /galleries/private/ 加密解密 UI

5. 搜索功能

配置（根 _config.yml 的 search 块）

三引擎：local（本地 search.json）+ algolia（Algolia API）+ pagefind（Pagefind 索引）。

实现效果

• 导航栏搜索框（#searchInput）
• 搜索弹窗实时结果
• /search.json 为本地搜索数据源

测试断言：页面含 #searchInput；/search.json 可访问；弹窗可打开。

6. 评论系统

配置（根 _config.yml）

comment: waline    # 评论引擎
waline:
  serverURL: https://waline.17lai.site
  ...

页面 front-matter 控制：comment: waline（文章/留言/友链/说说页）。

实现效果

Waline 评论框（Markdown/Emoji/点赞/后台管理）。

测试断言：文章/msg/friends/bb 页含 #comments；waline 初始化脚本存在。

7. 暗色模式

配置（主题 _config.yml）

dark_mode:
  enable: true
  default: auto   # auto | light | dark

• auto：优先 prefers-color-scheme，其次本地时间 18:00–6:00 自动暗色
• 切换按钮：手动切换后覆盖默认模式

实现效果

[data-user-color-scheme="dark"] 属性驱动全套 CSS 变量切换，图片/图表自适应。

测试断言：CSS 含 [data-user-color-scheme="dark"] 规则；切换按钮可切换明暗。

8. 加密文章

配置（根 _config.yml）

encrypt:
  tags:
    - 私密    # 按标签加密
  default_abstract: 本文已加密
  ...

文章只需打上加密标签，阅读时需输入密码。

实现效果

文章页显示解密 UI（#hbePass），输入正确密码后渲染正文。

测试断言：tag 加密文章含 #hbePass 解密 UI。

9. RSS / 站点地图

配置（根 _config.yml）

feed:            # hexo-feed 生成
  type: atom
  path: atom.xml
sitemap:         # hexo-generator-sitemap
  path: sitemap.xml

产物

• /rss.xml、/atom.xml、/feed.json — 订阅源
• /sitemap.xml、/baidusitemap.xml — 搜索引擎抓取

测试断言：/rss.xml、/atom.xml、/feed.json、/sitemap.xml 均可访问。

10. PWA

配置（根 _config.yml + userConfig/sw.tmp.js）

pwa:
  enable: true
  manifest: ...   # 名称/图标/主题色

sw.tmp.js 是 Service Worker 模板，CI 时注入离线缓存版本号 17lai-cache-{时间戳} 生成 source/sw.js。

实现效果

• 可安装（manifest）
• 离线缓存静态资源
• 版本更新自动刷新

测试断言：/sw.js 可访问，SW 注册正常（localhost 豁免）。

附：布局页面功能速查表