上一篇：安装、配置与本地预览 · 系列总目录 · 下一篇：一图流背景与明暗主题

前言

安装 Butterfly 只是让主题能够运行，真正决定网站是否好用的是信息架构：访客怎样返回首页、从哪里寻找文章、文章卡片展示什么信息、目录是否清楚、侧栏是否提供有效入口。

本文将围绕 _config.butterfly.yml 的核心页面配置展开。目标不是打开所有功能，而是搭建一套清晰、稳定并且方便继续扩展的基础布局。

一、先理解配置的覆盖关系

Butterfly 页面通常同时受到三层数据影响：

1
2
3
4
5
主题默认配置
    ↓ 被覆盖
根目录 _config.butterfly.yml
    ↓ 单页可继续覆盖
文章或页面 Front Matter

例如全站允许显示文章目录：

1
2
3
toc:
  post: true
  page: false

某篇特殊文章仍然可以在 Front Matter 中单独控制：

1
toc: false

设计配置时应遵循：

  • 大多数页面都适用的规则放进主题配置。
  • 只有少数页面例外时，在 Front Matter 中覆盖。
  • 不要为了一个页面修改主题模板。

二、配置导航栏

Logo、站点标题和文章标题

1
2
3
4
5
nav:
  logo: /img/weblogo.svg
  display_title: false
  display_post_title: true
  fixed: false

各项作用如下：

字段 作用
logo 左上角 Logo
display_title 导航栏是否显示网站名称
display_post_title 文章页滚动后是否显示文章标题
fixed 导航栏是否始终固定在顶部

Logo 如果需要适配复杂背景，可以准备黑白两个版本，再通过页面状态或背景亮度切换。这类判断已经超出原生配置范围，通常需要自定义 CSS 或 JavaScript。

一级和二级菜单

1
2
3
4
5
6
7
8
9
10
menu:
  首页: / || fas fa-home
  文章||fas fa-archive:
    归档: /archives/ || fas fa-archive
    标签: /tags/ || fas fa-tags
    分类: /categories/ || fas fa-folder-open
  社交||fas fa-comments:
    友链: /link/ || fas fa-link
  网站||fas fa-globe:
    日志: /log/ || fas fa-hammer

一级菜单后带有子项时，会成为下拉菜单。菜单不要堆得太满，移动端空间有限，常用入口保持在 4～6 个一级分组通常更加清楚。

三、设置头像与个人信息

1
2
3
4
5
6
7
avatar:
  img: /img/avatar.png
  effect: false

social:
  fab fa-github: https://github.com/your-name || GitHub || '#24292e'
  fas fa-envelope: mailto:you@example.com || Email || '#4a7dbe'

侧栏作者卡片：

1
2
3
4
5
6
7
8
9
aside:
  card_author:
    enable: true
    description: 记录学习、开发与生活
    button:
      enable: true
      icon: fab fa-github
      text: 访问 GitHub
      link: https://github.com/your-name

个人简介适合保持简短。完整介绍更适合单独建立“关于”页面。

四、首页文章卡片

选择卡片布局

1
index_layout: 3

Butterfly 5.x 提供多种布局：

值 效果
1 左图右文
2 右图左文
3 封面左右交替
4 上图下文
5 信息显示在封面上
6 瀑布流，上图下文
7 瀑布流，信息覆盖封面

布局 3 比较适合传统个人博客；布局 4 更像内容平台；布局 6 和 7 适合大量图片内容。

控制摘要

1
2
3
index_post_content:
  method: 2
  length: 500

推荐在重要文章中主动填写：

1
description: 用一两句话说明文章解决什么问题。

如果简介较长，可以在 CSS 中使用多行截断，并在悬浮时通过提示层展示完整内容。不要直接把卡片高度无限拉长，否则首页会因每篇简介长度不同而失去节奏。

设置每页文章数量

分页数量属于 Hexo 配置，应修改根目录 _config.yml：

1
2
3
index_generator:
  per_page: 10
  order_by: -date

十篇左右比较适合一般博客。文章卡片尺寸较大时可以降低到 6～8 篇，瀑布流则可以适当增加。

五、封面、页首图和背景不是同一个概念

一篇文章可以这样配置：

1
2
cover: /img/post-covers/article.webp
top_img: /img/banners/article-wide.webp
  • cover 主要显示在首页卡片、归档和相关推荐中。
  • top_img 主要显示在文章标题区域。
  • background 是整个网站页面背后的背景。
  • footer_img 是页脚背景。

同一张图片不一定适合同时作为封面和页首图。封面可能是竖图或方图，而页首通常需要横向构图。如果强行共用，background-size: cover 会裁掉大量内容。

推荐准备：

1
2
3
4
文章封面：适合卡片比例
文章页首：宽幅图片
全站背景：桌面横屏版本
手机背景：手机竖屏版本

Butterfly 全局封面配置：

1
2
3
4
5
6
7
cover:
  index_enable: true
  aside_enable: true
  archives_enable: true
  default_cover:
    - /img/post-covers/default-1.webp
    - /img/post-covers/default-2.webp

本站进一步使用了封面图池脚本：没有显式封面的文章会随机分配一次，并把结果持久保存。这个功能不是 Butterfly 原生能力。

六、文章日期、分类和标签

1
2
3
4
5
6
7
8
9
10
11
12
13
14
post_meta:
  page:
    date_type: created
    date_format: date
    categories: true
    tags: false
    label: true
  post:
    position: left
    date_type: both
    date_format: date
    categories: true
    tags: true
    label: true

page 是首页文章卡片上的元信息，post 是文章详情页。

文章 Front Matter：

1
2
3
4
5
6
7
date: 2026-07-30 20:00:00
updated: 2026-07-31 18:00:00
categories:
  - Web 开发
tags:
  - Hexo
  - Butterfly

Hexo 通常不会因为正文被编辑就可靠地自动更新 updated。是否自动读取文件修改时间还会受到文件系统、Git 和部署环境影响，因此需要准确更新时间时，建议主动维护这个字段或编写生成脚本。

七、文章目录与阅读功能

1
2
3
4
5
6
7
toc:
  post: true
  page: false
  number: true
  expand: false
  style_simple: false
  scroll_percent: true

目录来自 Markdown 标题层级：

1
2
3
## 一级章节
### 二级章节
#### 三级章节

不要为了字体变大而跳级使用标题，否则目录结构和搜索引擎语义都会混乱。

其他常用阅读功能：

1
2
3
4
5
6
7
8
9
10
11
wordcount:
  enable: true
  post_wordcount: true
  min2read: true
  total_wordcount: true

copy:
  enable: true
  copyright:
    enable: true
    limit_count: 500

代码块可以配置复制、语言标签和高度限制：

1
2
3
4
5
6
code_blocks:
  height_limit: 400
  word_wrap: false
  copy: true
  language: true
  shrink: false

较长的源码会被限制在固定高度内，读者需要时再展开，不会让文章被几百行代码完全占满。

八、版权、相关文章和过期提醒

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
post_copyright:
  enable: true
  author_href: https://example.com/
  license: CC BY-NC-SA 4.0
  license_url: https://creativecommons.org/licenses/by-nc-sa/4.0/

related_post:
  enable: true
  limit: 6

noticeOutdate:
  enable: true
  style: flat
  limit_day: 365
  position: top
  message_prev: 距离本文最后更新已经
  message_next: 天，部分内容可能已经过时。

技术教程很容易随着依赖版本变化而失效。显示更新时间和过期提醒，比假装文章永远正确更加负责。

九、组织侧栏

1
2
3
4
5
6
aside:
  enable: true
  hide: false
  button: true
  mobile: true
  position: right

Butterfly 预留的卡片包括：

  • 作者信息
  • 公告
  • 最近文章
  • 最新评论
  • 分类
  • 标签
  • 归档
  • 文章系列
  • 网站信息

建议只启用真正帮助导航的卡片。例如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
aside:
  card_announcement:
    enable: true
    content: 网站还在持续建设中
  card_recent_post:
    enable: true
    limit: 5
    sort: date
  card_categories:
    enable: false
  card_tags:
    enable: false
  card_webinfo:
    enable: true
    post_count: true
    last_push_date: true

如果分类和标签已经有独立的可视化页面，侧栏再显示一遍反而会增加噪声。

十、统一页脚

1
2
3
4
5
6
7
8
footer_img: /img/background.webp

footer:
  owner:
    enable: true
    since: 2025
  custom_text:
  copyright: true

如果文章页脚意外继承文章封面，应明确指定 footer_img。页脚内容可以通过 custom_text 或注入脚本扩展，但建议保持克制：

  • 版权和建站年份
  • 框架与主题来源
  • 运行时间或状态
  • 一句简短格言

页脚信息应覆盖在背景上，而不是和背景一起降低透明度。

十一、本篇检查清单

完成配置后，逐项检查：

  • Logo 在浅色和深色背景上是否可见
  • 桌面导航和手机菜单是否都能使用
  • 首页摘要长度是否稳定
  • 封面是否被过度裁切
  • 文章目录是否与标题层级一致
  • 分类和标签链接是否正确
  • 侧栏是否存在重复信息
  • 页脚在所有文章中是否统一

执行：

1
2
3
npm run clean
npm run build
npm run server

下一篇将进入视觉改造：把页首、正文和页脚连成一张完整背景，并分别处理亮色、暗色、桌面和手机画面。

参考资料与声明

本文结合本站实际配置整理。部分结构与文字由 AI 协助完成，配置字段请以所使用版本的官方文档为准。

上一篇：安装、配置与本地预览 · 返回系列总目录 · 下一篇：一图流背景与明暗主题