布局与页面

本页梳理 matery 主题的布局与页面相关功能：文章布局特性、侧边栏组件、响应式断点、相册、搜索、评论、暗色模式、加密、RSS/站点地图、PWA。每个功能给出配置位置与使用方法。

配置分两处：主题配置 themes/matery/_config.yml（布局/外观/交互）与站点配置 _config.yml（插件/生成器）。下面逐一标注。注意：本项目 CI 构建时主题配置文件会被 userConfig/_config.tmp.yml 模板覆盖，修改请同步模板（见「安装与主题配置」篇）。

1. 文章布局特性

1.1 上下篇导航

用途：文章底部展示上一篇/下一篇卡片，按时间排序自动取相邻文章，引导读者连续阅读。

启用（主题配置，位于 post 块内）：

post:
  prev_next:
    enable: true

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

1.2 版权声明

用途：文章底部展示版权与转载许可，注明作者、原文链接与许可协议。

启用（主题配置，位于 post 块内）：

post:
  copyright:
    enable: true          # 显示版权声明
  license: 'cc_by_nc_sa'  # 默认转载规则（CC BY-NC-SA 4.0）

默认许可对整个站点生效；单篇文章可在 front-matter 用 reprintPolicy 覆盖：

reprintPolicy: cc_by_nc   # 本篇改为"署名-非商业性使用"

可用规则：cc_by、cc_by_nd、cc_by_sa、cc_by_nc、cc_by_nc_nd、cc_by_nc_sa。

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

1.3 文章时效提示

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

启用（主题配置，位于 post 块内；注意当前默认 enable: false）：

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

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

1.4 TOC 目录

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

启用（主题配置，位于 post 块内）：

post:
  toc:
    enable: true                        # 全局开关
    placement: right                    # 置于板块左侧或右侧：left | right
    headingSelector: "h1,h2,h3,h4,h5,h6" # 参与目录的标题级别
    collapseDepth: 0                    # 折叠深度，0 全部折叠
    showToggleBtn: true                 # 显示展开/收缩按钮

单篇文章关闭：front-matter 加 toc: false。

效果：桌面端侧边栏目录树随滚动高亮；移动端折叠收起。

1.5 广告位

用途：文章侧边栏预留广告卡片位（TOC 同区域），可配置多条、自由启停。

配置（主题配置，位于 post 块内，数组可增删）：

post:
  advertisements:
    - id: "ad-1"
      text: "自用超便宜的 VPS 服务商推荐"
      link: "https://example.com/your-aff-link"
      background: "#6670ff"
      background_dark: "#3a4399"
      colspan: 1     # 卡片占列宽
      enable: true   # false 则隐藏

效果：侧边栏 TOC 下方展示彩色广告卡片，支持明暗两套背景色。

2. 页面级组件（widgets）

以下页面由主题生成器自动渲染，无需配置，随内容自动更新：

页面	组件	说明
`/categories/`	分类雷达图	canvas 雷达图展示各分类文章数量分布
`/tags/`	标签云 + 词云	chip 样式标签列表；canvas 词云字号 ∝ 文章数
`/archives/`	归档时间线	按年/月垂直时间线，圆点 + 年份折叠
`/about/`	站点统计图表	多组 canvas 图表（文章数/分类/标签/时间线等）

3. 响应式断点

配置（themes/matery/source/css/_variables/base.styl，Stylus 变量）：

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

各断点布局表现：

断点	布局表现
`< 768px`	导航折叠为汉堡菜单，正文单列，侧边栏隐藏
`768–992px`	平板布局，侧边栏收起
`> 992px`	桌面多栏（正文 + 侧边栏 + TOC）
`> 1400px`	特效启用（樱花/水波等）

布局基于 Materialize 栅格自适应，无需手动维护。

4. 相册功能

数据源（source/_data/galleries.yml，单点维护）：

2020:
  cover: /medias_webp/images/01.webp
  description: 2020 年跨年
  photos:
    - url: /medias_webp/images/01.webp      # 形式一：完整对象（url/title/desc）
      title: "2020跨年"
    - /medias_webp/images/02.webp           # 形式二：仅路径
    - dir: /medias_webp/featureimages/      # 形式三：目录，自动扫描全部图片
      title_prefix: "图"

新建相册：

hexo new gallery <名称>

生成 source/galleries/<名称>/index.md（front-matter 只需 title + layout: gallery）。加密相册加 password 字段，进入需解密。

效果：/galleries/ 列表卡片 + 封面；内页 lightGallery 灯箱浏览，图片标题/描述显示 caption。

5. 搜索功能

配置（主题配置的 search 块，三引擎）：

search:
  algolia:
    enable: true        # Algolia 引擎（applicationID/apiKey/indexName 见主题配置）
    indexName: "blog"
  local:
    enable: true        # 本地搜索：hexo generate 时由生成器输出 /search.json
    path: /search.json
    field: post         # 搜索范围：post | page | all
    content: true       # 是否索引正文
  pagefind:
    enable: true        # Pagefind 静态索引（构建后浏览器端搜索）
    output_subdir: pagefind

效果：导航栏搜索框，弹窗实时结果；/search.json 为本地搜索数据源；加密文章自动从索引排除。

6. 评论系统

配置（主题配置）：

waline:
  enable: true
  serverURL: 'https://waline.17lai.site'  # 你的 Waline 服务端
  lang: zh-CN
  dark: 'html[data-user-color-scheme="dark"]'  # 跟随暗色模式
  login: enable
  wordLimit: 1000
  pageSize: 10

页面 front-matter 控制开关：comments: true / comments: false。

效果：Waline 评论框，支持 Markdown/Emoji/点赞/后台管理，自动适配明暗模式。

7. 暗色模式

配置（主题配置）：

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

auto：优先遵循 prefers-color-scheme，其次按本地时间 18:00–6:00 自动进入暗色
手动切换按钮会覆盖默认模式（记忆用户选择）

效果：[data-user-color-scheme="dark"] 属性驱动全套 CSS 变量切换，图片、图表、评论组件均自适应。

8. 加密文章

配置（根 _config.yml，插件 hexo-blog-encrypt）：

encrypt:
  enable: true
  abstract: 有东西被加密了, 请输入密码查看.
  message: 您好, 这里需要密码.
  tags:                     # 按标签加密：命中标签的文章自动加密
    - {name: 私人, password: "********"}
  wrong_pass_message: 抱歉, 这个密码看着不太对, 请再试试.
  autoSave: true            # 密钥缓存到 localStorage，刷新免输密码

用法：

标签加密：文章打上 encrypt.tags 中列出的标签，阅读时需输入对应密码
单篇加密：文章 front-matter 直接写 password: "********"

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

9. RSS / 站点地图

配置（根 _config.yml，hexo-feed + hexo-generator-sitemap）：

feed:             # 三类订阅源独立开关
  rss:
    enable: true
    output: "rss.xml"
  atom:
    enable: true
    output: "atom.xml"
  jsonFeed:
    enable: true
    output: "feed.json"
  limit: 10

sitemap:          # 通用站点地图
  path: sitemap.xml

baidusitemap:     # 百度站点地图
  path: baidusitemap.xml

产物：/rss.xml、/atom.xml、/feed.json 订阅源；/sitemap.xml、/baidusitemap.xml 供搜索引擎抓取。

10. PWA

配置（主题配置 + 模板）：

pwa:
  enable: true

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

效果：可安装（manifest + 主题色）；离线缓存静态资源；版本更新后自动刷新。

附：布局功能速查表

功能	位置	配置位置	说明
上下篇导航	文章底部	主题 `post.prev_next`	按时间取相邻文章
版权声明	文章底部	主题 `post.copyright`（含 `license` 子键）	front-matter `reprintPolicy` 单篇覆盖
时效提示	文章开头	主题 `post.outdate`	默认关闭，按天数分级
TOC 目录	文章侧边栏	主题 `post.toc`	front-matter `toc: false` 单篇关闭
广告位	侧边栏	主题 `post.advertisements`	数组多卡片，可单独启停
分类雷达图	`/categories/`	自动渲染	无需配置
标签云/词云	`/tags/`	自动渲染	无需配置
归档时间线	`/archives/`	自动渲染	无需配置
关于页图表	`/about/`	自动渲染	无需配置
响应式断点	全局	`base.styl` 的 `$breakpoint-*` 变量	368/768/992/1200/1400
相册	`/galleries/`	`source/_data/galleries.yml`	`hexo new gallery` 建页
搜索	导航栏	主题 `search`（algolia/local/pagefind）	三引擎可独立启停
评论	文章/留言等页	主题 `waline`	front-matter `comments` 控制开关
暗色模式	全局	主题 `dark_mode`	`auto` 跟随系统 + 时段
加密	文章页	根 `encrypt`	标签加密或 front-matter `password`
RSS/Sitemap	根路径	根 `feed` / `sitemap` / `baidusitemap`	三类订阅源 + 双站点地图
PWA	全局	主题 `pwa` + `userConfig/sw.tmp.js`	离线缓存 + 可安装