本文对 Butterfly 主题所有配置项，逐一项解释作用、可选值、用法，可当作永久配置查阅手册。

目录

  2. 一、导航设置 nav
  3. 二、导航菜单 menu
  4. 三、代码块设置 code_blocks
  5. 四、社交链接 social
  6. 五、网站图标、头像、顶部大图
    1. favicon
    2. avatar 侧边栏头像
    3. 全局顶部大图控制
    4. 网站背景 background
  7. 六、文章封面 cover
  8. 七、错误图片 & 404 页面
  9. 八、文章元信息 post_meta
  10. 九、首页布局配置
    1. subtitle 首页副标题 + 打字机
    2. index_layout 首页文章排版
    3. 首页文章摘要
  11. 十、文章页面配置
    1. toc 文章目录
    2. post_copyright 文章版权声明
    3. reward 打赏
    4. post_edit 在线编辑源码按钮
    5. related_post 相关推荐文章
    6. post_pagination 上下篇文章
    7. noticeOutdate 文章过时提醒
  12. 十一、页脚 footer
  13. 十二、侧边栏 aside 全套配置
  14. 十三、右侧悬浮按钮
  15. 十四、全局基础
  16. 十五、数学公式 math
  17. 十六、站内搜索 search
  18. 十七、文章分享 share
  19. 十八、评论系统 comments
  20. 十九、在线聊天 chat
  21. 二十、统计分析
  22. 二十一、广告 ads
  23. 二十二、站点验证
  24. 二十三、主题美化与动效
  25. 二十四、图片灯箱 lightbox
  26. 二十五、标签插件
  27. 二十六、其他

一、导航设置 nav

1
2
3
4
5
nav:
 logo: # 导航栏 Logo 图片地址
 display_title: true # 是否显示网站标题文字
 display_post_title: true # 文章页导航栏是否显示文章标题
 fixed: false # 是否固定导航栏，滚动时置顶

二、导航菜单 menu

自行配置顶部导航菜单，格式：名称: 链接 || 图标

1
2
3
4
5
6
7
menu:
 # 示例：
 # 首页: / || fas fa-home
 # 归档: /archives/ || fas fa-archive
 # 标签: /tags/ || fas fa-tags
 # 分类: /categories/ || fas fa-folder
 # 关于: /about/ || fas fa-user

三、代码块设置 code_blocks

1
2
3
4
5
6
7
8
9
code_blocks:
 theme: light # 代码块主题：darker / pale night / light / ocean / false
 macStyle: false # 是否开启 Mac 窗口红绿灯样式
 height_limit: false # 代码块最大高度，单位px，false不限制
 word_wrap: false # 代码是否自动换行
 copy: true # 显示复制按钮
 language: true # 显示代码语言标签
 shrink: false # 是否默认折叠长代码
 fullpage: false # 是否开启代码全屏按钮

四、社交链接 social

格式：图标: 链接 || 文字 || 颜色

1
2
3
social:
 # fab fa-github: https://github.com/xxx || Github || '#24292e'
 # fas fa-envelope: mailto:xxx@gmail.com || Email || '#4a7dbe'

五、网站图标、头像、顶部大图

favicon

网站浏览器标签小图标

1
favicon: /img/favicon.png

avatar 侧边栏头像

1
2
3
avatar:
 img: /img/butterfly-icon.png # 头像图片地址
 effect: false # 头像是否开启悬浮特效

全局顶部大图控制

1
2
3
4
5
6
7
8
9
disable_top_img: false # 全局禁用所有页面顶部大图
default_top_img: # 页面无单独大图时默认顶部图
index_img: # 首页顶部大图
archive_img: # 归档页顶部大图
tag_img: # 标签页默认大图
tag_per_img: # 给每个标签单独设置封面
category_img: # 分类页默认大图
category_per_img: # 给每个分类单独设置封面
footer_img: false # 页脚背景图，false关闭

网站背景 background

可填纯色、图片URL、多张图片数组随机切换

1
background:

六、文章封面 cover

1
2
3
4
5
6
cover:
 index_enable: true # 首页显示文章封面
 aside_enable: true # 侧边栏显示文章封面
 archives_enable: true # 归档页显示文章封面
 default_cover: # 文章无封面时默认兜底图
 # - xxx.jpg

七、错误图片 & 404 页面

1
2
3
4
5
6
7
error_img:
 flink: /img/friend_404.gif # 友链失效兜底图
 post_page: /img/404.jpg # 文章图片加载失败兜底图
error_404:
 enable: false # 开启自定义404页面
 subtitle: 'Page Not Found' # 404副标题
 background: /img/error-page.png # 404背景图

八、文章元信息 post_meta

控制首页、文章页显示时间、分类、标签

1
2
3
4
5
6
7
8
9
10
11
12
13
14
post_meta:
 page: # 首页
 date_type: created # created / updated / both
 date_format: date # date标准日期 / relative相对时间
 categories: true # 显示分类
 tags: false # 显示标签
 label: true # 显示角标标签
 post: # 文章内页
 position: left # 信息居左/居中 left/center
 date_type: both
 date_format: date
 categories: true
 tags: true
 label: true

九、首页布局配置

1
2
index_site_info_top: # 首页文字区域距离顶部高度
index_top_img_height: # 首页顶部大图高度

subtitle 首页副标题 + 打字机

1
2
3
4
5
6
subtitle:
 enable: false # 开启副标题
 effect: true # 打字机效果
 typed_option: # typed.js 自定义参数
 source: false # 一言接口 1/2/3 关闭false
 sub: # 自定义副标题文字

index_layout 首页文章排版

1~7 种布局：

  1. 封面左信息右

  2. 封面右信息左

  3. 左右交错

  4. 封面在上信息在下

  5. 信息悬浮封面

  6. 瀑布流

  7. 瀑布流+悬浮信息

    1
    index_layout: 3

    首页文章摘要

    1
    2
    3
    index_post_content:
    method: 3 # 1描述 / 2都显示 / 3自动摘要 / false关闭
    length: 500 # 摘要截取字数

    十、文章页面配置

    toc 文章目录

    1
    2
    3
    4
    5
    6
    7
    toc:
    post: true # 文章页开启目录
    page: false # 普通页面开启目录
    number: true # 目录带序号
    expand: false # 默认展开目录
    style_simple: false # 简约样式
    scroll_percent: true # 滚动显示阅读百分比

    post_copyright 文章版权声明

    1
    2
    3
    4
    5
    6
    post_copyright:
    enable: true
    decode: false
    author_href:
    license: CC BY-NC-SA 4.0
    license_url: https://creativecommons.org/licenses/by-nc-sa/4.0/

    reward 打赏

    1
    2
    3
    4
    5
    6
    7
    reward:
    enable: false
    text:
    QR_code:
    # - img: /img/wechat.jpg
    # link:
    # text: wechat

    post_edit 在线编辑源码按钮

    1
    2
    3
    post_edit:
    enable: false
    url: # GitHub 仓库编辑地址前缀

    related_post 相关推荐文章

    1
    2
    3
    4
    related_post:
    enable: true
    limit: 6 # 推荐数量
    date_type: created # 按创建/更新排序

    post_pagination 上下篇文章

    1
    post_pagination: 1

    noticeOutdate 文章过时提醒

    1
    2
    3
    4
    5
    noticeOutdate:
    enable: false
    style: flat # simple / flat
    limit_day: 365 # 多少天后提醒
    position: top # top / bottom

    十一、页脚 footer

    1
    2
    3
    4
    5
    6
    7
    8
    9
    footer:
    nav:
    owner:
    enable: true
    since: 2025 # 建站起始年份
    copyright:
    enable: true
    version: true # 显示主题版本
    custom_text: # 自定义底部文字

    十二、侧边栏 aside 全套配置

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    aside:
    enable: true # 开启侧边栏
    hide: false # 默认是否隐藏
    button: true # 显示侧边栏切换按钮
    mobile: true # 手机端是否显示
    position: right # left / right
    display:
    archive: true
    tag: true
    category: true
    card_author: # 作者卡片
    enable: true
    description:
    button:
    enable: true
    icon: fab fa-github
    text: Follow Me
    link: https://github.com/xxxxxx
    card_announcement: # 公告卡片
    enable: true
    content: This is my Blog
    card_recent_post: # 最新文章
    enable: true
    limit: 5
    sort: date
    card_newest_comments: # 最新评论
    enable: false
    card_categories: # 分类
    enable: true
    limit: 8
    expand: none
    card_tags: # 标签云
    enable: true
    limit: 40
    color: false
    card_archives: # 归档
    enable: true
    type: monthly # monthly / yearly
    order: -1
    card_post_series: # 文章系列
    enable: true
    card_webinfo: # 网站统计
    enable: true
    post_count: true
    last_push_date: true
    runtime_date: # 网站运行时间起始日期

    十三、右侧悬浮按钮

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    rightside_bottom: # 按钮距离底部距离
    translate: # 简繁切换
    enable: false
    readmode: true # 阅读模式
    darkmode: # 暗黑模式
    enable: true
    button: true
    autoChangeMode: false
    rightside_scroll_percent: false # 回到顶部显示百分比
    rightside_item_order: # 自定义右侧按钮顺序

    十四、全局基础

    1
    2
    3
    4
    5
    6
    7
    8
    9
    anchor: # 锚点链接
    copy: # 复制内容版权
    enable: true
    wordcount: # 字数统计插件
    enable: false
    busuanzi: # 不蒜子访问统计
    site_uv: true
    site_pv: true
    page_pv: true

    十五、数学公式 math

    1
    2
    3
    math:
    use: # mathjax / katex
    per_page: true

    十六、站内搜索 search

    1
    2
    3
    search:
    use: # algolia_search / local_search / 留空关闭
    placeholder:

    十七、文章分享 share

    1
    2
    share:
    use: sharejs # sharejs / addtoany

    十八、评论系统 comments

    支持：Disqus / Gitalk / Valine / Waline / Twikoo / Giscus 等

    1
    2
    3
    comments:
    use: # 填写评论系统名称
    lazyload: false

    十九、在线聊天 chat

    1
    2
    chat:
    use: # chatra / tidio / crisp

    二十、统计分析

    百度统计、谷歌分析、Cloudflare 分析、微软 Clarity、Umami

    1
    2
    3
    4
    5
    baidu_analytics:
    google_analytics:
    cloudflare_analytics:
    microsoft_clarity:
    umami_analytics:

    二十一、广告 ads

    1
    2
    3
    4
    5
    6
    google_adsense:
    enable: false
    ad:
    index:
    aside:
    post:

    二十二、站点验证

    1
    2
    3
    site_verification:
    # - name: google-site-verification
    # content: xxxxxx

    二十三、主题美化与动效

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    theme_color: # 自定义全站主题色
    rounded_corners_ui: true # 卡片圆角
    preloader: false # 页面加载动画
    enter_transitions: true # 页面切换过渡
    display_mode: light # 默认 light / dark
    # 背景动效
    canvas_ribbon:
    enable: false
    canvas_nest:
    enable: false
    fireworks: # 点击烟花
    enable: false
    click_heart: # 点击爱心
    enable: false

    二十四、图片灯箱 lightbox

    1
    lightbox: # fancybox / medium_zoom

    二十五、标签插件

    1
    2
    3
    4
    5
    6
    7
    8
    9
    mermaid: # 流程图/思维导图
    enable: false
    chartjs: # 数据图表
    enable: false
    note: # 彩色提示块
    pjax: # 无刷新跳转
    enable: false
    lazyload: # 图片懒加载
    enable: false

    二十六、其他

    1
    2
    3
    4
    inject: # 自定义注入 html/css/js
    head:
    bottom:
    CDN: # 全局CDN配置