布局与页面

本页梳理 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'  # 默认转载规则（copyright 子键，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）

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

3. 响应式断点

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

$breakpoint-sm  = 368px   // 超小屏（手机竖屏）
$breakpoint-md  = 768px   // 平板/手机横屏
$breakpoint-lg  = 992px   // 桌面
$breakpoint-xl  = 1200px  // 大屏
$breakpoint-fun = 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: "********"
• Wiki 页加密：wiki 页面（layout: wiki）同样支持 front-matter password: "********"（2026-09-03 确认）——服务端 after_post_render 不限制 layout，前端解锁 UI 随加密内容自注入，与 post 加密体验一致

Wiki 页 front-matter 清单（2026-09-03）

wiki 页面（layout: wiki）支持的 front-matter 与文章一致，常用项：

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

ECharts 图表（2026-09-03 统一）

• 启用：front-matter 加 echarts: true（加载 libs echarts 5.6.0 + echarts-gl 2.1.0）
• 文章内图表：{% echarts 宽 高 %} + option JSON（宽默认 100%、高默认 400px，首参宽、次参高）
• 明暗：自动适配（init 传当前主题，切换时重建）
• GL 图表：option 含 grid3D/globe 等 GL 组件时自动可用（echarts-gl 已加载）
• 注意：echarts 6 要求 xAxis 显式声明 type（category/value）

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 + 主题色）；离线缓存静态资源；版本更新后自动刷新。

11. 独立页面（Standalone Pages）

以下页面由主题提供专用 layout 模板，需在 source/ 下创建对应页面（front-matter 指定 layout），页面正文写在 md 文件中，模板负责渲染。

11.1 av 影视页（layout: av）

用途：影视/资源分享页，结构类似关于页——音乐播放器 + 视频 + 我的相册 + 资源分享正文。

数据源（主题配置）：

• theme.music（音乐播放器，见「交互视觉」篇 §9）
• theme.video（视频播放器，见「交互视觉」篇 §10）
• theme.myGallery（我的相册，见「侧边栏组件」篇 §8）
• page.content（页面正文，资源分享列表）

创建（当前项目未建此页）：

hexo new page av

source/av/index.md front-matter：

---
title: 影视资源
layout: av
---

11.2 movies 电影页（layout: movies）

用途：励志短片页，模板内硬编码一个 Bilibili iframe 播放器。

数据源：无数据文件——短片地址硬编码在 themes/matery/layout/movies.ejs 的 iframe src 中，更换短片需编辑模板。

创建（项目已有 source/movies/index.md）：

---
title: 视频
layout: movies
---

11.3 msg 留言页（layout: msg）

用途：留言板。正文（博客时间线等）+ 留言信封组件 + 评论区。

评论开关：模板经 inject_point('pageComments') 注入评论，front-matter comment: waline（或 comments: true）开启。

letter 信封组件：正文末尾自动渲染 _partial/letter——信封展开动画 + 留言表单提示（样式 letter.styl，文案 i18n letter.*）。

创建（项目已有 source/msg/index.md）：

---
title: 留言板
layout: msg
toc: false          # 关闭 TOC（模板按 theme.post.toc.enable && page.toc !== 'false' 判断）
comment: waline
---

11.4 friends 友链页（layout: friends）

用途：友链卡片墙（Masonry 瀑布流）+ 页面正文 + 评论区。

数据源（source/_data/friends.yml，纯数组，模板经 site.data.friends 读取）：

- name: 友链名称            # 必填，卡片标题
  url: https://example.com  # 必填，跳转地址
  avatar: /favicon.png      # 必填，头像
  introduction: 一句话介绍  # 必填
  title: 前去学习           # 可选，按钮文字

说明：卡片背景色按列表顺序循环 frind-card1~frind-card10；页面正文（page.content）显示在友链列表下方，评论区经 linksComments 注入点渲染。

创建（项目已有 source/friends/index.md）：

---
title: 'For My Friends!'
layout: friends
comment: waline
---

11.5 contact 联系页（layout: contact）

用途：联系页——弹幕互动 + 评论区。页面正文 + 弹幕表单（文字/链接/速度）+ 评论。

弹幕：基于 LeanCloud（AV）存储的 barrager 弹幕，valine/waline 任一启用（theme.valine.enable 或 theme.waline.enable）即显示弹幕表单。

客服组件：daovoice / tidio / tuxiaochao 在线客服配置见「交互视觉」篇 §14，此处为页面本身。

创建（当前项目未建此页）：

hexo new page contact

source/contact/index.md front-matter：

---
title: 联系我
layout: contact
---

11.6 404 页（layout: 404）

用途：未找到页面提示 + 搜索入口 + 倒计时跳转首页（8 秒）。

自定义方式（项目已有 source/404.md）：

---
title: 404
layout: 404
excerpt: "Oops～，我崩溃了！找不到你想要的页面 :("   # 显示在页面描述处
---

说明：excerpt 显示为页面描述；banner 图按日期每日切换（/medias_webp/banner/{0-6}.webp）。

附：布局功能速查表