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

一、导航设置 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配置