导航菜单与首页
本页讲解顶部导航菜单(一级/二级菜单)与首页(封面轮播、Banner、文章瀑布流)的配置。全部在主题配置中完成。
主题配置以
userConfig/_config.tmp.yml为权威源(CI 时覆盖主题配置),下文配置段均出自其中。阅读方式:每节都按「如何启用 → 常用选项 → 全部可调项 → 边界与冲突」展开,先看效果,再看产生该效果的对应配置,复制即可用。
1. 导航菜单(menu)
用途:顶部导航栏菜单项。支持一级菜单(直接链接)与二级菜单(children 下拉)。
学习路径:如何启用 → 常用选项 → 全部可调项 → 边界与冲突
1.1 如何启用
效果:页面顶部横栏出现菜单项;鼠标悬停带 children 的项时展开下拉面板,点击跳转对应 URL。
对应配置(主题配置,menu 段):
menu:
home: # 一级菜单:直接链接
url: / # 一级菜单必须填 url(有二级菜单时可不填)
icon: fas fa-home # Font Awesome 图标(v5.15 图标名)
class: menu-2d-home # live2d 选择器:提示文字框定位用
nav:
url: https://nav.17lai.site/
icon: fas fa-suitcase
class: menu-2d-nav
target: _blank # 新标签页打开
so:
url: https://so.17lai.site/
icon: fas fa-mask
class: menu-2d-sosuo
target: _blank
multimedia: # 二级菜单:children 数组
icon: fas fa-music
class: menu-2d-media
children:
- name: music # 菜单显示名(i18n 键)
url: /musics/
icon: fas fa-music
class: menu-2d-musics
- name: gallery
url: /galleries/
icon: fas fa-image
- name: movie
url: /movies/
icon: fas fa-film
posts:
icon: fas fa-folder-plus
children:
- name: tags # /tags/ 标签页
url: /tags/
icon: fas fa-tags
- name: categories # /categories/ 分类页
url: /categories/
icon: fas fa-bookmark
- name: archives # /archives/ 归档页
url: /archives/
icon: fas fa-archive1.2 常用选项
① 新增一级菜单
效果:顶部多出一个图标菜单项,点击直接跳转到该 URL。
对应配置:
menu:
about:
url: /about/
icon: fas fa-user② 新增二级菜单
效果:该菜单变成下拉面板,悬停展开子项。
对应配置:
menu:
posts:
icon: fas fa-folder-plus
children:
- name: tags
url: /tags/
icon: fas fa-tags③ 外链新窗口打开
效果:点击后在新标签页打开,不离开本站。
对应配置:
menu:
nav:
url: https://nav.17lai.site/
target: _blank1.3 全部可调项
| 键 | 类型 | 默认 | 可选值/范围 | 作用 |
|---|---|---|---|---|
menu.<name>.url | string | — | 站内绝对路径或完整 URL | 一级菜单链接(一级必填) |
menu.<name>.icon | string | — | Font Awesome v5.15 图标类名 | 菜单图标 |
menu.<name>.class | string | — | 任意 class 名 | live2d 提示框定位选择器 |
menu.<name>.target | string | — | _blank / _self | 打开方式 |
menu.<name>.children | array | — | 子项数组 | 二级菜单 |
menu.<name>.children[].name | string | — | i18n 键 | 子菜单显示名 |
menu.<name>.children[].url | string | — | 站内路径或 URL | 子菜单链接 |
menu.<name>.children[].icon | string | — | Font Awesome 类名 | 子菜单图标 |
menu.<name>.children[].class | string | — | 任意 class 名 | live2d 定位选择器 |
1.4 边界与冲突
- 新增菜单:在
menu下加一项(一级)或往某菜单加children(二级)。name是 i18n 键(languages/zh-CN.yml中的对应文案);icon在 Font Awesome v5.15 查;target: _blank用于外链新窗口。 class仅用于 live2d 看板娘提示框定位,无看板娘可省略。- 菜单项
url写成/musics/(绝对路径)而非musics,否则与url拼接后可能出错。
1.5 小结
- 最小可用:一个
url+icon就是一级菜单 - 要下拉:改用
children,父级可不填url - 外链:记得
target: _blank - 别用相对路径:
/xxx/而不是xxx
2. 首页封面轮播(cover)
用途:首页顶部的文章封面轮播图。文章通过 front-matter 的
cover/coverImg进入轮播。学习路径:如何启用 → 常用选项 → 全部可调项 → 边界与冲突
2.1 如何启用
效果:首页顶部出现大图轮播,可用左右按钮与底部圆点切换,按 intervalTime 自动轮播;点击图片进入对应文章。
对应配置(主题配置,cover 段):
cover:
showPrevNext: true # 左右切换按钮
showIndicators: true # 底部指示器(小圆点)
autoLoop: true # 自动轮播
duration: 180 # 切换动画时长(毫秒)
intervalTime: 8000 # 自动切换间隔(毫秒)
useConfig: false # true 时用 _data/covers.json 配置轮播文章
video:
enable: false # 轮播背景视频(填 src 视频地址数组)
src:
- https://example.com/video1.mp42.2 常用选项
① 让某篇文章进轮播
效果:该文章封面出现在轮播中。
对应配置(文章 front-matter):
cover: true② 换轮播图
效果:该文章在轮播里用指定图片,而非默认封面。
对应配置(文章 front-matter):
coverImg: /path/to/img.webp③ 关掉自动轮播
效果:只保留手动切换,不再每隔几秒跳下一张。
对应配置:
cover:
autoLoop: false④ 用数据文件统一配置
效果:轮播内容改由 source/_data/covers.json 决定,忽略文章 front-matter。
对应配置:
cover:
useConfig: true文章 front-matter 控制(优先级说明,出自配置注释):
| front-matter 键 | 作用 |
|---|---|
hide: true | 完全隐藏文章(不进首页列表,也不进封面轮播) |
cover: true | 文章进入封面轮播(前提:hide 不为 true) |
coverImg: /path/to/img.webp | 自定义轮播图片(优先于 cover 的默认图) |
优先级:
hide: true>cover: true。hide: true + cover: true→ 文章完全隐藏,不进轮播。
2.3 全部可调项
| 键 | 类型 | 默认 | 可选值/范围 | 作用 |
|---|---|---|---|---|
cover.showPrevNext | bool | true | true / false | 左右切换按钮 |
cover.showIndicators | bool | true | true / false | 底部指示器 |
cover.autoLoop | bool | true | true / false | 自动轮播 |
cover.duration | number | 180 | 毫秒 | 切换动画时长 |
cover.intervalTime | number | 8000 | 毫秒 | 自动切换间隔 |
cover.useConfig | bool | false | true / false | 用 _data/covers.json 配置 |
cover.video.enable | bool | false | true / false | 轮播背景视频 |
cover.video.src | array | — | 视频 URL 数组 | 背景视频源 |
front-matter hide | bool | — | true | 完全隐藏文章 |
front-matter cover | bool | — | true | 进入轮播 |
front-matter coverImg | string | — | 图片路径 | 自定义轮播图 |
2.4 边界与冲突
useConfig: true时文章 front-matter 的cover/coverImg失效,改由_data/covers.json决定。hide: true优先级最高,cover: true无效。video.enable: true时轮播背景播放视频,src为空则不显示。
2.5 小结
- 最小可用:文章 front-matter
cover: true - 想换图:加
coverImg - 隐藏某篇:
hide: true,一票否决 - 统一管理:
useConfig: true+covers.json
3. 首页 Banner 与副标题
用途:首页头图(独立于全局 banner)、打字机副标题、按钮与社交链接、"梦想"语录。
学习路径:如何启用 → 常用选项 → 全部可调项 → 边界与冲突
3.1 如何启用
效果:首页顶部整屏 Banner(默认 100% 视口高),图上叠 30% 黑色蒙版,标题下方逐字打出的副标题,右侧社交图标行。
对应配置(主题配置,index 段):
index:
banner_img: /img/default.png # 首页头图(相对或绝对路径)
banner_img_height: 100 # 头图高度(屏幕百分比,0-100)
banner_mask_alpha: 0.3 # 黑色蒙版不透明度(0-1,1 全不透)
slogan: # 首页副标题独立设置
enable: true
text: "An elegant Material-Design theme for Hexo" # 为空则用 hexo 的 subtitle
api: # 通过 API 取副标题(返回 JSON)
enable: false
url: ""
method: "GET" # GET | POST | PUT
headers: {}
keys: [] # 取值字段,如 ['data','content']3.2 常用选项
① 换首页头图
效果:首页 Banner 换成指定图片(只影响首页,不影响文章页)。
对应配置:
index:
banner_img: /medias_webp/banner/home.webp② 调 Banner 高度
效果:100 占满一屏,50 只留半屏。
对应配置:
index:
banner_img_height: 50③ 改副标题
效果:打字机文案变成新文本;text 为空则退回站点 subtitle。
对应配置:
index:
slogan:
enable: true
text: "深度思考,深入生活"④ 用 API 提供副标题
效果:副标题内容来自接口返回的 JSON 字段,请求失败回落到 text。
对应配置:
index:
slogan:
api:
enable: true
url: "https://example.com/slogan.json"
method: "GET"
keys: ['data', 'content']首页专属部件:
dream: # "梦想"语录(banner 下方文字)
enable: true
showTitle: false
title: 追梦
text: "凡我所失,皆非我所有……"
indexbtn: # banner 第二个按钮
enable: true
name: GitHub
icon: fab fa-github
url: https://github.com/appotry
socialLink: # banner 第二行个人信息(留空即不显示)
github: https://github.com/appotry
dockerhub: https://hub.docker.com/u/bloodstar
email: admin@17lai.fun
rss: true # true/false3.3 全部可调项
| 键 | 类型 | 默认 | 可选值/范围 | 作用 |
|---|---|---|---|---|
index.banner_img | string | — | 图片路径或 URL | 首页头图 |
index.banner_img_height | number | 100 | 0–100(视口百分比) | 头图高度 |
index.banner_mask_alpha | number | 0.3 | 0–1 | 黑色蒙版不透明度 |
index.slogan.enable | bool | true | true / false | 副标题开关 |
index.slogan.text | string | — | 任意字符串 | 副标题文本(空则用站点 subtitle) |
index.slogan.api.enable | bool | false | true / false | 用 API 取副标题 |
index.slogan.api.url | string | "" | URL | 接口地址 |
index.slogan.api.method | string | "GET" | GET / POST / PUT | 请求方法 |
index.slogan.api.headers | map | {} | 请求头 | 自定义请求头 |
index.slogan.api.keys | array | [] | 字段路径数组 | 取值字段 |
dream.enable | bool | true | true / false | 语录开关 |
dream.showTitle | bool | false | true / false | 是否显示语录标题 |
dream.title | string | — | 任意字符串 | 语录标题 |
dream.text | string | — | 任意字符串 | 语录内容 |
indexbtn.enable | bool | true | true / false | 第二个按钮开关 |
indexbtn.name | string | — | 任意字符串 | 按钮文字 |
indexbtn.icon | string | — | Font Awesome 类名 | 按钮图标 |
indexbtn.url | string | — | URL | 按钮链接 |
socialLink.<platform> | string | — | URL 或空 | 社交图标链接(留空不显示) |
socialLink.rss | bool | — | true / false | RSS 图标 |
3.4 边界与冲突
index.banner_*只作用于首页;文章页头图见「文章页配置」篇的post.banner_*。slogan.api依赖打字机效果(fun_features.typing.enable),未开时 API 副标题不显示。socialLink留空的平台不渲染图标;rss: true/false是开关而非链接。dream.showTitle: false时只显示text。
3.5 小结
- 最小可用:
banner_img+slogan.text - 想简洁:
banner_mask_alpha调低 + 关dream - 副标题不写字:留空即用站点
subtitle - API 副标题无效:先开打字机
4. 首页文章列表(瀑布流)
用途:首页正文区以瀑布流(Masonry)展示文章卡片。布局由主题自动完成,配置控制摘要、跳转方式、元信息与置顶。
学习路径:如何启用 → 常用选项 → 全部可调项 → 边界与冲突
4.1 如何启用
效果:首页下方出现多列文章卡片,每张显示封面、标题、日期/分类/标签;滚动到底自动加载下一页。
对应配置(主题配置,index 段内):
index:
auto_excerpt:
enable: true # 自动截取文章摘要
post_url_target: _self # 打开文章方式:_blank 新标签 | _self 本页
post_meta: # 文章卡片元信息
date: true
category: true
tag: true
post_sticky: # 置顶文章标题前显示图标
enable: true
icon: "iconfont icon-top"4.2 常用选项
① 自动摘要
效果:卡片显示正文前若干字,而非只有标题。
对应配置:
index:
auto_excerpt:
enable: true② 新标签打开文章
效果:点击卡片在新标签页打开。
对应配置:
index:
post_url_target: _blank③ 卡片元信息
效果:卡片上显示/隐藏日期、分类、标签。
对应配置:
index:
post_meta:
date: true
category: true
tag: false④ 置顶文章
效果:sticky 值较大的文章排前面,标题前显示置顶图标。
对应配置(文章 front-matter):
sticky: 1文章 front-matter 控制卡片:
title: 示例文章
sticky: 1 # 数字越大越靠前(首页置顶)
index_img: /medias_webp/cover/5w2h.webp # 卡片封面图
hide: false # true 时从首页列表隐藏4.3 全部可调项
| 键 | 类型 | 默认 | 可选值/范围 | 作用 |
|---|---|---|---|---|
index.auto_excerpt.enable | bool | true | true / false | 自动截取摘要 |
index.post_url_target | string | _self | _blank / _self | 文章打开方式 |
index.post_meta.date | bool | true | true / false | 卡片显示日期 |
index.post_meta.category | bool | true | true / false | 卡片显示分类 |
index.post_meta.tag | bool | true | true / false | 卡片显示标签 |
index.post_sticky.enable | bool | true | true / false | 置顶图标开关 |
index.post_sticky.icon | string | — | 图标类名 | 置顶图标 |
front-matter sticky | number | — | 正整数,越大越前 | 首页置顶权重 |
front-matter index_img | string | post.default_index_img | 图片路径 | 卡片封面 |
front-matter hide | bool | false | true / false | 从首页列表隐藏 |
4.4 边界与冲突
- 未指定
index_img时用主题配置post.default_index_img兜底(见「文章页配置」篇),两者都为空则不显示封面。 - 瀑布流布局基于 Masonry 库,页面图片加载完成后自动重排,无需手动维护。
hide: true同时对首页列表与封面轮播生效(见 §2)。
4.5 小结
- 最小可用:不用配,默认就是瀑布流
- 卡片太素:开
auto_excerpt+ 设index_img - 想置顶:front-matter
sticky: 1 - 某篇不想出现:
hide: true
附:导航与首页速查表
| 功能 | 配置位置 | 说明 |
|---|---|---|
| 导航菜单 | 主题 menu | 一级 url/icon/class/target,二级 children |
| 封面轮播 | 主题 cover | 自动轮播 + 指示器;front-matter cover/coverImg/hide |
| 首页 Banner | 主题 index | banner_img/高度/蒙版 + slogan 副标题 |
| 梦想语录 | 主题 dream | banner 下方语录文字 |
| 首页按钮 | 主题 indexbtn | 第二个按钮(名称/图标/链接) |
| 社交链接 | 主题 socialLink | 第二行图标,留空不显示 |
| 文章列表 | 主题 index + front-matter | 摘要/跳转/元信息/置顶/封面 |