加载中...

加载中...

导航菜单与首页

本页讲解顶部导航菜单(一级/二级菜单)与首页(封面轮播、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-archive

1.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: _blank

1.3 全部可调项

键类型默认可选值/范围作用
menu.<name>.urlstring—站内绝对路径或完整 URL一级菜单链接(一级必填)
menu.<name>.iconstring—Font Awesome v5.15 图标类名菜单图标
menu.<name>.classstring—任意 class 名live2d 提示框定位选择器
menu.<name>.targetstring—_blank / _self打开方式
menu.<name>.childrenarray—子项数组二级菜单
menu.<name>.children[].namestring—i18n 键子菜单显示名
menu.<name>.children[].urlstring—站内路径或 URL子菜单链接
menu.<name>.children[].iconstring—Font Awesome 类名子菜单图标
menu.<name>.children[].classstring—任意 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.mp4

2.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.showPrevNextbooltruetrue / false左右切换按钮
cover.showIndicatorsbooltruetrue / false底部指示器
cover.autoLoopbooltruetrue / false自动轮播
cover.durationnumber180毫秒切换动画时长
cover.intervalTimenumber8000毫秒自动切换间隔
cover.useConfigboolfalsetrue / false用 _data/covers.json 配置
cover.video.enableboolfalsetrue / false轮播背景视频
cover.video.srcarray—视频 URL 数组背景视频源
front-matter hidebool—true完全隐藏文章
front-matter coverbool—true进入轮播
front-matter coverImgstring—图片路径自定义轮播图

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/false

3.3 全部可调项

键类型默认可选值/范围作用
index.banner_imgstring—图片路径或 URL首页头图
index.banner_img_heightnumber1000–100(视口百分比)头图高度
index.banner_mask_alphanumber0.30–1黑色蒙版不透明度
index.slogan.enablebooltruetrue / false副标题开关
index.slogan.textstring—任意字符串副标题文本(空则用站点 subtitle)
index.slogan.api.enableboolfalsetrue / false用 API 取副标题
index.slogan.api.urlstring""URL接口地址
index.slogan.api.methodstring"GET"GET / POST / PUT请求方法
index.slogan.api.headersmap{}请求头自定义请求头
index.slogan.api.keysarray[]字段路径数组取值字段
dream.enablebooltruetrue / false语录开关
dream.showTitleboolfalsetrue / false是否显示语录标题
dream.titlestring—任意字符串语录标题
dream.textstring—任意字符串语录内容
indexbtn.enablebooltruetrue / false第二个按钮开关
indexbtn.namestring—任意字符串按钮文字
indexbtn.iconstring—Font Awesome 类名按钮图标
indexbtn.urlstring—URL按钮链接
socialLink.<platform>string—URL 或空社交图标链接(留空不显示)
socialLink.rssbool—true / falseRSS 图标

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.enablebooltruetrue / false自动截取摘要
index.post_url_targetstring_self_blank / _self文章打开方式
index.post_meta.datebooltruetrue / false卡片显示日期
index.post_meta.categorybooltruetrue / false卡片显示分类
index.post_meta.tagbooltruetrue / false卡片显示标签
index.post_sticky.enablebooltruetrue / false置顶图标开关
index.post_sticky.iconstring—图标类名置顶图标
front-matter stickynumber—正整数,越大越前首页置顶权重
front-matter index_imgstringpost.default_index_img图片路径卡片封面
front-matter hideboolfalsetrue / 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主题 indexbanner_img/高度/蒙版 + slogan 副标题
梦想语录主题 dreambanner 下方语录文字
首页按钮主题 indexbtn第二个按钮(名称/图标/链接)
社交链接主题 socialLink第二行图标,留空不显示
文章列表主题 index + front-matter摘要/跳转/元信息/置顶/封面
评论
数据加载中 ...