Butterfly document - Theme Configuration

This article is translated from ChatGPT.

Quick Read of Configuration Files

You can quickly understand all the configuration comments, making your configuration files more convenient. If you encounter any unclear configurations, you can find more detailed information in this article.












nav:
  
  logo:
  display_title: true
  display_post_title: true
  
  fixed: false

menu:
  
  
  
  





code_blocks:
  
  theme: light
  macStyle: false
  
  height_limit: false
  word_wrap: false

  
  copy: true
  language: true
  
  shrink: false
  fullpage: false




social:
  
  





favicon: /img/favicon.png

avatar:
  img: /img/butterfly-icon.png
  effect: false


disable_top_img: false


default_top_img:


index_img:


archive_img:


tag_img:




tag_per_img:


category_img:




category_per_img:


footer_img: false



background:

cover:
  
  index_enable: true
  aside_enable: true
  archives_enable: true
  
  default_cover:
    


error_img:
  flink: /img/friend_404.gif
  post_page: /img/404.jpg


error_404:
  enable: false
  subtitle: 'Page Not Found'
  background: /img/error-page.png

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








index_site_info_top:

index_top_img_height:


subtitle:
  enable: false
  
  effect: true
  
  
  typed_option:
  
  
  
  
  
  
  
  source: false
  
  sub:









index_layout: 3






index_post_content:
  method: 3
  
  length: 500





toc:
  post: true
  page: false
  number: true
  expand: false
  
  style_simple: false
  scroll_percent: true

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:
  enable: false
  text:
  QR_code:
    
    
    
    
    
    



post_edit:
  enable: false
  
  
  url:


related_post:
  enable: true
  
  limit: 6
  
  date_type: created





post_pagination: 1


noticeOutdate:
  enable: false
  
  style: flat
  
  limit_day: 365
  
  position: top
  message_prev: It has been
  message_next: days since the last update, the content of the article may be outdated.




footer:
  nav:
  owner:
    enable: true
    since: 2019
  custom_text:
  
  copyright:
    enable: true
    version: true





aside:
  enable: true
  hide: false
  
  button: true
  mobile: true
  
  position: 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
    sort_order:
  card_newest_comments:
    enable: false
    sort_order:
    limit: 6
    
    storage: 10
    avatar: true
  card_categories:
    enable: true
    
    limit: 8
    
    expand: none
    sort_order:
  card_tags:
    enable: true
    
    limit: 40
    color: false
    
    orderby: random
    
    order: 1
    sort_order:
  card_archives:
    enable: true
    
    type: monthly
    
    format: MMMM YYYY
    
    order: -1
    
    limit: 8
    sort_order:
  card_post_series:
    enable: true
    
    series_title: false
    
    orderBy: 'date'
    
    order: -1
  card_webinfo:
    enable: true
    post_count: true
    last_push_date: true
    sort_order:
    
    
    
    runtime_date:






rightside_bottom:


translate:
  enable: false
  
  default: 繁
  
  defaultEncoding: 2
  
  translateDelay: 0
  
  msgToTraditionalChinese: '繁'
  
  msgToSimplifiedChinese: '簡'


readmode: true


darkmode:
  enable: true
  
  button: true
  
  
  
  
  autoChangeMode: false
  
  start:
  end:


rightside_scroll_percent: false




rightside_item_order:
  enable: false
  
  hide:
  
  show:


rightside_config_animation: true





anchor:
  
  auto_update: false
  
  click_to_scroll: false

photofigcaption: false

copy:
  enable: true
  
  copyright:
    enable: false
    limit_count: 150


wordcount:
  enable: false
  
  post_wordcount: true
  
  min2read: true
  
  total_wordcount: true


busuanzi:
  site_uv: true
  site_pv: true
  page_pv: true








math:
  
  
  use:
  per_page: true
  hide_scrollbar: false

  mathjax:
    
    enableMenu: true
    
    tags: none

  katex:
    
    copy_tex: false





search:
  
  
  use:
  placeholder:

  
  algolia_search:
    
    hitsPerPage: 6

  
  local_search:
    
    preload: false
    
    top_n_per_article: 1
    
    unescape: false
    CDN:

  
  
  docsearch:
    appId:
    apiKey:
    indexName:
    option:





share:
  
  
  use: sharejs

  
  
  sharejs:
    sites: facebook,twitter,wechat,weibo,qq

  
  
  addtoany:
    item: facebook,twitter,wechat,sina_weibo,facebook_messenger,email,copy_link





comments:
  
  
  
  
  use:
  
  text: true
  
  
  lazyload: false
  
  count: false
  
  card_post_count: false



disqus:
  shortname:
  
  apikey:



disqusjs:
  shortname:
  apikey:
  option:



livere:
  uid:



gitalk:
  client_id:
  client_secret:
  repo:
  owner:
  admin:
  option:



valine:
  appId:
  appKey:
  avatar: monsterid
  
  serverURLs:
  bg:
  
  visitor: false
  option:



waline:
  serverURL:
  bg:
  
  pageview: false
  option:



utterances:
  repo:
  
  issue_term: pathname
  
  light_theme: github-light
  dark_theme: photon-dark
  js:
  option:



facebook_comments:
  app_id:
  
  user_id:
  pageSize: 10
  
  order_by: social
  lang: zh_TW



twikoo:
  envId:
  region:
  
  visitor: false
  option:



giscus:
  repo:
  repo_id:
  category_id:
  light_theme: light
  dark_theme: dark
  js:
  option:



remark42:
  host:
  siteId:
  option:



artalk:
  server:
  site:
  
  visitor: false
  option:





chat:
  
  
  use:
  
  
  rightside_button: false
  
  button_hide_show: false


chatra:
  id:


tidio:
  public_key:


crisp:
  website_id:






baidu_analytics:


google_analytics:


cloudflare_analytics:


microsoft_clarity:


umami_analytics:
  enable: false
  
  serverURL:
  website_id:
  option:
  UV_PV:
    site_uv: false
    site_pv: false
    page_pv: false
    
    token:


google_tag_manager:
  tag_id:
  domain:






google_adsense:
  enable: false
  auto_ads: true
  js: https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js
  client:
  enable_page_level_ads: true



ad:
  
  index:
  
  aside:
  
  post:





site_verification:
  
  
  
  





























category_ui:
tag_ui:


rounded_corners_ui: true


text_align_justify: false


mask:
  header: true
  footer: true


preloader:
  enable: false
  
  
  
  source: 1
  
  pace_css_url:


enter_transitions: true


display_mode: light


beautify:
  enable: false
  
  field: post
  
  title_prefix_icon:
  
  title_prefix_icon_color:



font:
  global_font_size:
  code_font_size:
  font_family:
  code_font_family:


blog_title_font:
  font_link:
  font_family:


hr_icon:
  enable: true
  
  icon:
  icon_top:



activate_power_mode:
  enable: false
  colorful: true
  shake: true
  mobile: false






canvas_ribbon:
  enable: false
  
  size: 150
  
  alpha: 0.6
  zIndex: -1
  click_to_change: false
  mobile: false


canvas_fluttering_ribbon:
  enable: false
  mobile: false



canvas_nest:
  enable: false
  
  color: '0,0,255'
  
  opacity: 0.7
  
  zIndex: -1
  
  count: 99
  mobile: false


fireworks:
  enable: false
  zIndex: 9999
  mobile: false


click_heart:
  enable: false
  mobile: false


clickShowText:
  enable: false
  text:
    
    
    
  fontSize: 15px
  random: false
  mobile: false









lightbox:






series:
  enable: false
  
  orderBy: 'title'
  
  order: 1
  number: true



abcjs:
  enable: false
  per_page: true



mermaid:
  enable: false
  
  code_write: false
  
  theme:
    light: default
    dark: dark



chartjs:
  enable: false
  
  
  
  fontColor:
    light: "rgba(0, 0, 0, 0.8)"
    dark: "rgba(255, 255, 255, 0.8)"
  
  borderColor:
    light: "rgba(0, 0, 0, 0.1)"
    dark: "rgba(255, 255, 255, 0.2)"
  
  scale_ticks_backdropColor:
    light: "transparent"
    dark: "transparent"


note:
  
  
  
  
  
  style: flat
  icons: true
  border_radius: 3
  
  
  light_bg_offset: 0






pjax:
  enable: false
  
  exclude:
    


aplayerInject:
  enable: false
  per_page: true




snackbar:
  enable: false
  position: bottom-left
  
  bg_light: '#49b1f5'
  bg_dark: '#1f1f1f'



instantpage: false



lazyload:
  enable: false
  
  native: false
  
  field: site
  placeholder:
  blur: false




pwa:
  enable: false
  manifest:
  apple_touch_icon:
  favicon_32_32:
  favicon_16_16:
  mask_icon:



Open_Graph_meta:
  enable: true
  option:
    
    
    
    
    
    
    



structured_data: true


css_prefix: true



inject:
  head:
    
  bottom:
    



CDN:
  
  
  
  
  internal_provider: local
  third_party_provider: jsdelivr

  
  version: false

  
  
  custom_format:

  option:

Language

Modify Hexo's configuration file _config.yml

The default language is en

The theme supports the following languages:

default (en)
zh-CN (Simplified Chinese)
zh-TW (Traditional Chinese)
zh-HK (Traditional Chinese)
ja (Japanese)
ko (Korean)




To modify various website data, such as title, subtitle, and personal information like email, please edit Hexo's `_config.yml`

![butterfly-docs-hexo-config.png](https://oss.012700.xyz/butterfly/2024/09/butterfly-docs-hexo-config.png)





```yaml
nav:
  
  logo: /xxxx.png
  display_title: true
  display_post_title: true
  
  fixed: false

Parameter	Explanation
logo	The website's logo, supports images, just input the image link
display_title	Whether to display the website title, write true or false
display_post_title	Whether to display the post title, write true or false
fixed	Whether to fix the status bar, write true or false

Home: / || fas fa-home
Archives: /archives/ || fas fa-archive
Tags: /tags/ || fas fa-tags
Categories: /categories/ || fas fa-folder-open
List||fas fa-list:
  Music: /music/ || fas fa-music
  Movie: /movies/ || fas fa-video
Link: /link/ || fas fa-link
About: /about/ || fas fa-heart

Must be /xxx/, followed by || to separate, then write the icon name.

If you do not wish to display an icon, the icon name can be omitted.

By default, subdirectories are expanded. If you want to hide them, add hide inside the subdirectory.

1
2
3

List||fas fa-list||hide:
  Music: /music/ || fas fa-music
  Movie: /movies/ || fas fa-video

Note： The text of the navigation can be changed as desired.

For example:

menu:
  Home: / || fas fa-home
  Timeline: /archives/ || fas fa-archive
  Tags: /tags/ || fas fa-tags
  Categories: /categories/ || fas fa-folder-open
  List||fa fa-heartbeat:
  Music: /music/ || fas fa-music
  Photos: /Gallery/ || fas fa-images
  Movies: /movies/ || fas fa-video
  Links: /link/ || fas fa-link
  About: /about/ || fas fa-heart

Code Blocks

All features within code blocks are only applicable to Hexo's built-in code rendering.

If using a third-party renderer, it may not be effective.

code_blocks:
  
  theme: light
  macStyle: false
  
  height_limit: false
  word_wrap: false

  
  copy: true
  language: true
  
  shrink: false
  fullpage: false

Parameter	Explanation
theme	Code highlight theme, options: darker / pale night / light / ocean / false
macStyle	Whether to use Mac style
height_limit	Code block height limit (unit: px), can be a number or false
word_wrap	Whether to automatically wrap lines
copy	Whether to show the copy button
language	Whether to show the language label
shrink	true: collapse code block / false: expand code block / none: expand code block and hide button
fullpage	Whether to show the full page button

Code Highlight Theme

Butterfly supports 4 types of code highlight styles:

darker
pale night
light
ocean

If you need a MacOS style code highlight, you can set macStyle to true.

Starting from version 3.0, the theme supports custom code color themes.

To learn how to create a custom theme, refer to the following article:

Custom Code Colors

Code Block Expand/Collapse

By default, code blocks are automatically expanded. You can set whether all code blocks are in a collapsed state, and they can be expanded by clicking >.

true All code blocks are collapsed and require clicking > to open.
false Code blocks are expanded and have a > click button.
none The > button is not displayed.

1	highlight_shrink: true

You can also add highlight_shrink in the front-matter of the corresponding markdown file for a post/page to configure it independently.

When highlight_shrink in the theme configuration file is set to true, you can add highlight_shrink: false in the front-matter to configure the article to expand code blocks individually.

When highlight_shrink in the theme configuration file is set to false, you can add highlight_shrink: true in the front-matter to configure the article to collapse code blocks individually.

highlight_shrink: true

highlight_shrink: false

highlight_shrink: none

Code Word Wrap

By default, Hexo does not implement automatic word wrapping for code during compilation. If you prefer not to have a horizontal scrollbar within the code block area, you might want to enable this feature.

1	code_word_wrap: true

If you are using highlight for rendering, you need to find your site's Hexo configuration file _config.yml and change line_number to false:

highlight:
  enable: true
  line_number: false 
  auto_detect: false
  tab_replace:

If you are using prismjs for rendering, you need to find your site's Hexo configuration file _config.yml and change line_number to false:

prismjs:
  enable: false
  preprocess: true
  line_number: false 
  tab_replace: ''

Before setting code_word_wrap

After setting code_word_wrap

Code Height Limit

Supported from version 3.7.0 and above

You can configure a height limit for code blocks. Any content exceeding this limit will be hidden, with a button to expand it shown.

1	highlight_height_limit: false

Notes:

The unit is px. Add a number directly, such as 200.
The actual height limit is highlight_height_limit + 30 px. An additional 30px is added to the limit to avoid showing the expand button when the code height exceeds the limit by just a little, resulting in no content being shown upon expansion.
This does not apply to code blocks that are hidden (with CSS display: none).

Butterfly supports font-awesome v6 icons.

The format is icon name: url || descriptive text || color

1
2
3

social:
  fab fa-github: https://github.com/xxxxx || Github || "#hdhfbb"
  fas fa-envelope: mailto:xxxxxx@gmail.com || Email || "#000000"

You can find the icon names here

PC:

Mobile:

Image Settings

Avatar

1
2
3

avatar:
  img: /img/avatar.png
  effect: true

Top Image

If you do not want to display the top image, you can directly configure disable_top_img: true

The order of obtaining the top image, if none are configured, the top image will not be displayed.

The order of obtaining the top image for pages:
Individually configured top_img > default_top_img in the configuration file
The order of obtaining the top image for article pages:
Individually configured top_img > cover > default_top_img in the configuration file

Values in the configuration:

Configuration	Explanation
index_img	Top image for the homepage
default_top_img	Default top image, displayed when the page's top_img is not configured
archive_img	Top image for the archive page
tag_img	Default top image for tag subpages
tag_per_img	Top image for tag subpages, can configure a top_img for each tag
category_img	Default top image for category subpages
category_per_img	Top image for category subpages, can configure a top_img for each category

For other pages (tags/categories/custom pages) and article pages, set the top_img in the front-matter of the corresponding markdown page.

All the above top_img can be configured with the following values:

Configuration Value	Effect
Leave empty	Display the default top_img (if any), otherwise display the default color (If the top_img of the article page is empty, the cover value will be displayed)
img link	Link to the image, display the configured image
Color ( HEX value - #0000FF RGB value - rgb(0,0,255) Color word - orange Gradient color - linear-gradient( 135deg, #E2B0FF 10%, #9F44D3 100%) )	Corresponding color
transparent	Transparent
false	Do not display top_img

tag_per_img and category_per_img are new in version 3.2.0, allowing individual configuration for tags and categories.

It is not recommended to configure different top images for each tag and category, as too many configurations will slow down the generation speed.

tag_per_img:
  aplayer: https://xxxxxx.png
  android: ddddddd.png

category_per_img：
  隨想: hdhdh.png
  推薦: ddjdjdjd.png

top_img: 'linear-gradient(20deg, #0062be, #925696, #cc426e, #fb0347)'

1 2	footer_img: true

Configuration Value	Effect
Leave empty/false	Display the default color
img link	Link to the image, display the configured image
Color ( HEX value - #0000FF RGB value - rgb(0,0,255) Color word - orange Gradient color - linear-gradient( 135deg, #E2B0FF 10%, #9F44D3 100%) )	Corresponding color
transparent	Transparent
true	Display the same as top_img

Website Background

The default display is white, you can set an image or color

1
2
3



background:

Note: If your website root directory is not '/', when using local images, you need to add your root directory.
For example: if the website is https://yoursite.com/blog, and you reference an image img/xx.png, then set the background to /blog/img/xx.png

Article Cover

In the markdown document of the article, add cover in the Front-matter and fill in the image address to be displayed.

If cover is not configured, you can set a default cover to display.

If you do not want to display the cover on the homepage, you can set it to false.

The order of obtaining the article cover: Front-matter cover >default_cover in the configuration file > false

cover:
  
  index_enable: true
  aside_enable: true
  archives_enable: true
  default_cover:

Parameter	Explanation
index_enable	Whether to display the article cover on the homepage
aside_enable	Whether to display the article cover in the aside
archives_enable	Whether to display the article cover on the archive page
default_cover	Default cover, can configure image link/color/gradient color etc.

When multiple images are configured, one will be randomly selected as the cover. The configuration should be written as

default_cover:
  - https://jsd.012700.xyz/gh/jerryc127/CDN@latest/cover/default_bg.png
  - https://jsd.012700.xyz/gh/jerryc127/CDN@latest/cover/default_bg2.png
  - https://jsd.012700.xyz/gh/jerryc127/CDN@latest/cover/default_bg3.png

Page Meta Display

This option is used to display related information about the article.

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

Home Page：

Parameter	Explanation
date_type	Displays the article's time, options: created / updated / both
date_format	Configures whether to show the exact time or relative time, options: date / relative
categories	Whether to display the article's categories
tags	Whether to display the article's tags
label	Whether to display text labels

Post：

Parameter	Explanation
position	Position of the article page meta display, options: left / center
date_type	Displays the article's time, options: created / updated / both
date_format	Configures whether to show the exact time or relative time, options: date / relative
categories	Whether to display the article's categories
tags	Whether to display the article's tags
label	Whether to display text labels

date_format is a new feature in version 3.2.0, allowing configuration of displaying exact or relative time.

Home Page

Home Page Top Image Size

By default, the display is full-screen, and site information is centered.




index_site_info_top:  
index_top_img_height:

Note: The value of index_top_img_height cannot be a percentage. If both are not filled, default values will be used.

Example: when

1	index_top_img_height: 400px

Effect:

Website Subtitle

Set a subtitle or favorite motto to display on the home page.


subtitle:
  enable: false
  
  effect: true
  
  
  typed_option:
  
  
  
  
  
  
  source: false
  
  sub:
    - Never put off till tomorrow what you can do today

Home Page Card Layout

The theme supports seven types of card layouts for the home page

1	index_layout: 3

配置值	解釋
1	Cover on the left, info on the right
2	Cover on the right, info on the left
3	Cover and info alternate between left and right
4	Cover on top, info on the bottom
5	Info displayed on the cover
6	Masonry layout - Cover on top, info on the bottom
7	Masonry layout - Info displayed on the cover

Just fill in the number, the default is 3

1: Cover on the left, info on the right

2: Cover on the right, info on the left

3: Cover and info alternate between left and right

4: Cover on top, info on the bottom

5: Info displayed on the cover

6: Masonry layout - Cover on top, info on the bottom

7: Masonry layout - Info displayed on the cover

Home Page Article Excerpts

Due to the theme's UI, home page article excerpts only support automatic excerpts and article description.






index_post_content:
  method: 3
  
  length: 500

Parameter	Description
method	Method to display article content, four options available 1 - Display only description 2 - Prefer description, if not configured, display auto excerpt 3 - Display only auto excerpt 4 - Do not display article content
length	Length of the auto excerpt, only needs to be configured when method is 2 or 3

Add description in front-matter:

Article Page

TOC (Table of Contents)

Display TOC (Table of Contents) in the aside.

toc:
  post: true
  page: false
  number: true
  expand: false
  
  style_simple: false
  scroll_percent: true

Attribute	Explanation
post	Whether to display TOC in article pages
page	Whether to display TOC in regular pages
number	Whether to show section numbers
expand	Whether to expand the TOC
style_simple	Simple mode (aside only shows TOC, only for articles)
scroll_percent	Whether to show scroll progress percentage

Configuring for Specific Articles

Add toc_number and toc at the top of your article's md file, and set them to true or false.

The theme will prioritize the Front-matter configuration of the article's Markdown file. If not configured, it will use the configuration in the theme configuration file.

Article Copyright

Display copyright and license information for your blog articles.

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/

Since Hexo 4.1, URLs are decoded by default, so Chinese URLs will be decoded. Set decode: true to display Chinese URLs.

If some articles (e.g., reprints) do not need to display copyright, you can set it individually in the article's Front-matter:

1	copyright: false

From version 3.0.0, individual articles can have their own copyright information. Set it individually in the article's Front-matter:

copyright_author: xxxx
copyright_author_href: https://xxxxxx.com
copyright_url: https://xxxxxx.com
copyright_info: 此文章版權歸 xxxxx 所有，如有轉載，請註明來自原作者

Copyright Display Screenshot

Article Donations/Sponsorship

At the end of each of your articles, you can add a donation button. You can configure the relevant QR codes yourself.

For those who haven't provided QR codes, you can configure an icon image for software and add the corresponding donation link. When users click the image, they'll be redirected to the link.

The link can be omitted, and it will default to the image link.

reward:
  enable: true
  text:
  QR_code:
    - img: /img/wechat.jpg
      link:
      text: WeChat
    - img: /img/alipay.jpg
      link:
      text: Alipay

Article Edit Button

Display an edit button next to the article title. When clicked, it will redirect to the corresponding link.



post_edit:
  enable: false
  
  
  url:

When the article cover is set to false or no cover configuration is available, the background for related articles will display the theme color.

The related articles recommendation is based on the tags associated with each article.

related_post:
  enable: true
  limit: 6 
  date_type: created

When the article cover is set to false or no cover configuration is available, the background for pagination will display the theme color.

You can configure the logic for pagination or disable pagination display altogether.






post_pagination: false

Parameter	Explanation
post_pagination: false	Disable pagination buttons
post_pagination: 1	Next post links to older post
post_pagination: 2	Next post links to newer post

Outdated Article Reminder

if you want to close the out-of-date reminder for certain articles, you can configure noticeOutdate: false in the corresponding article's front-matter to close it individually.

You can choose to display an outdated notice for articles based on their update time.


noticeOutdate:
  enable: false
  
  style: flat
  
  limit_day: 365
  
  position: top
  message_prev: It has been
  message_next: days since the last update, the content of the article may be outdated.

Configuration	Explanation
enable	Enable article outdated notice
style	Notice style: simple / flat
limit_day	Set how many days before the notice appears (default: 365 days)
position	Notice position: top / bottom
message_prev	Custom message (prefix)
message_next	Custom message (suffix)

The footer navigation bar can be configured to display at the top of the footer, or not displayed at all.

You can configure it or leave it empty.
If left empty, the old version of the footer will be shown.

Example configuration:

nav:
  - width:
    content:
      - title: Docs
        item:
          - title: 🚀 Get Started
            url: /posts/21cfbf15/
          - title: 📑 Theme Pages
            url: /posts/dc584b87/
          - title: 📌 Theme Configuration
            url: /posts/4aa8abbe/
          - title: ⚔️ Tag Plugins
            url: /posts/ceeb73f/
          - title: ❓ Q&A
            url: /posts/98d20436/
          - title: ⚡️ Advanced Tutorials
            url: /posts/4073eda/
  - content:
    - title: Others
      item:
        - title: Gallery
          url: /Gallery/
        - title: Message Board
          url: /messageboard/
        - title: Talking
          url: /talking/
        - title: Example
          url: /link/
        - title: Friends
          url: /links/
  - content:
    - title: Framework
      item:
        - title: Hexo
          url: https://hexo.io/
        - title: Butterfly
          url: https://butterfly.js.org/
  - content:
    - title: Sponsor
      item:
        - title: Alipay
          url: https://jsd.012700.xyz/gh/jerryc127/CDN/Photo/alipay.jpg
          html: "<img src='https://jsd.012700.xyz/gh/jerryc127/CDN/Photo/alipay.jpg' alt='JerryC' width='100px' height='100px'>"

Configuration explanation

Option	Description
width	Set the width, recommended to leave unset (optional)
content	Content of the footer navigation bar, supports multiple sections, each with multiple items
title	Title of the footer navigation bar section
item	Items in the footer navigation bar, supports multiple items, each with a title and link
title	Title of the navigation item
url	Link of the navigation item
html	HTML content for the navigation item, supports images and other content

Blog Start Year

The since option displays the starting year of your site. It appears at the bottom of the page.

footer:
  owner:
    enable: true
    since: 2018

The custom_text option allows you to add custom text to the footer. You can use HTML here to write statements or other content.

1	custom_text: Hi, welcome to my <a href="https://butterfly.js.org/">blog</a>!

For those who need to include an ICP (Internet Content Provider) number, you can also add it within the custom_text:

1	custom_text: <a href="ICP link"><img class="icp-icon" src="ICP image"><span>Record Number：xxxxxx</span></a>

Aside

Aside Configuration

aside:
  enable: true
  hide: false
  
  button: true
  mobile: true
  
  position: 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
    sort_order:
  card_newest_comments:
    enable: false
    sort_order:
    limit: 6
    
    storage: 10
    avatar: true
  card_categories:
    enable: true
    
    limit: 8
    
    expand: none
    sort_order:
  card_tags:
    enable: true
    
    limit: 40
    color: false
    
    orderby: random
    
    order: 1
    sort_order:
  card_archives:
    enable: true
    
    type: monthly
    
    format: MMMM YYYY
    
    order: -1
    
    limit: 8
    sort_order:
  card_post_series:
    enable: true
    
    series_title: false
    
    orderBy: 'date'
    
    order: -1
  card_webinfo:
    enable: true
    post_count: true
    last_push_date: true
    sort_order:
    
    
    
    runtime_date:

sort_order is used to configure the order of each card. If not configured, it will follow the order in the theme configuration file. The smaller the number, the higher its position.

Configuration	Explanation
enable	Whether to enable the sidebar
hide	Whether to hide the sidebar by default
button	Whether to show the button to hide/show the sidebar
mobile	Whether to display the sidebar on mobile devices
position	Sidebar position, left / right
display.archive	Whether to display aside on the archive page
display.tag	Whether to display aside on the tag page
display.category	Whether to display aside on the category page
card_author.enable	Whether to display the author card
card_author.description	Author description information
card_author.button.enable	Whether to display the button
card_author.button.icon	Button icon, you can find the icon name here: https://fontawesome.com/icons?d=gallery&m=free
card_author.button.text	Button text
card_author.button.link	Button link
card_announcement.enable	Whether to display the announcement card
card_announcement.content	Announcement content (HTML tags can be used)
card_recent_post.enable	Whether to display the recent posts card
card_recent_post.limit	Number of posts to display, 0 for all
card_recent_post.sort	Sorting method, date / updated
card_newest_comments.enable	Whether to display the newest comments card
card_newest_comments.limit	Number of comments to display, 0 for all
card_newest_comments.storage	Storage time in minutes, saved to local storage to avoid re-fetching data on every refresh
card_newest_comments.avatar	Whether to display avatars
card_categories.enable	Whether to display the categories card
card_categories.limit	Number of categories to display, 0 for all
card_categories.expand	Whether to expand categories, none / true / false
card_tags.enable	Whether to display the tags card
card_tags.limit	Number of tags to display, 0 for all
card_tags.color	Whether to display tag colors
card_tags.orderby	Tag sorting method, random / name / length
card_tags.order	Sorting method, 1 for ascending, -1 for descending
card_archives.enable	Whether to display the archives card
card_archives.type	Archive type, monthly / yearly
card_archives.format	Archive display format, e.g., YYYY年MM月
card_archives.order	Sorting method, 1 for ascending, -1 for descending
card_archives.limit	Number of archives to display, 0 for all
card_post_series.enable	Whether to display the post series card
card_post_series.series_title	Whether to display the series name
card_post_series.orderBy	Sorting method, title / date
card_post_series.order	Sorting method, 1 for ascending, -1 for descending
card_webinfo.enable	Whether to display the website info card
card_webinfo.post_count	Whether to display the number of posts
card_webinfo.last_push_date	Whether to display the last update date
card_webinfo.runtime_date	Display the website runtime, no need to enable, leave blank (if enabled, the format must be Month/Day/Year Time or Year/Month/Day Time)

Currently, three comment systems - Livere, Facebook Comments, and Giscus do not support displaying the latest comments.

The latest comments are only loaded upon refreshing the page and do not update in real-time.

Due to API rate limits, to avoid excessive calls, the theme defaults to a storage duration of 10 minutes. This means, after a call, the data will be stored in localStorage, and refreshing the website within 10 minutes will only retrieve data from localStorage. After the 10-minute period, refreshing the page will call the API to load new data. (A storage configuration was added in version 3.6.0, allowing for custom cache duration settings.)

Click to Visit

Bottom Right Buttons

Button Position

When the chat service is enabled, the chat service button may cover the bottom right buttons. You can set the position of these buttons. It's not recommended to adjust this unless necessary, the default is fine.

1 2	rightside_bottom:

The default unit is px, just add the number directly.

Simplified and Traditional Chinese Conversion

The theme has a built-in simple conversion function between Simplified and Traditional Chinese, using a one-to-one pairing. In cases of multiple Traditional characters for a single Simplified character or vice versa, correct conversion may not occur. Please be aware.

After enabling, there will be a Simplified/Traditional conversion button at the bottom right.

translate:
  enable: true
  
  default: Simplified
  
  defaultEncoding: 1
  
  translateDelay: 0
  
  msgToTraditionalChinese: 'Traditional'
  
  msgToSimplifiedChinese: 'Simplified'

Reading Mode

Reading mode removes content other than the article itself to avoid distractions during reading.

It only appears on article pages, with a reading mode button at the bottom right.

1	readmode: true

Dark Mode

There will be a dark mode button at the bottom right.


darkmode:
  enable: true
  button: true
  autoChangeMode: false
  
  start: 
  end:

Parameter	Explanation
button	Whether to display the day/night mode switch button at the bottom right
autoChangeMode	The mode of automatic switching autoChangeMode: 1 Changes according to the system, browsers/systems that do not support this will switch to light mode between the start and end times autoChangeMode: 2 Only switches to light mode between the start and end times, other times will be dark mode autoChangeMode: false Cancels automatic switching
start	The start time for light mode
end	The end time for light mode

Scroll Status Percentage

1 2	rightside_scroll_percent: true

Button Sorting

You can sort the buttons at the bottom right corner.

Note： Do not duplicate




rightside_item_order:
  enable: false
  hide: 
  show:

Global Configuration

Page Anchors

When page anchors are enabled, the page link will be updated according to the header ID as you scroll.
(Note: Each update will leave a history record. So if an article has many anchors, the web page's history record will be extensive.)


anchor:
  
  auto_update: false
  
  click_to_scroll: false

Parameter	Explanation
auto_update	When scrolling, the URL will update according to the header ID. Default is `false`.
click_to_scroll	Click the headline to scroll and update the anchor. Default is `false`.

Image Captions

You can enable Figcaption to display image descriptions.

It will prioritize the title attribute of the image, followed by the alt attribute.

1	photofigcaption: true

Copy Configuration

You can configure whether the website content can be copied and whether to add copyright information to the copied content.

copy:
  enable: true
  
  copyright:
    enable: false
    limit_count: 150

Parameter	Explanation
enable	Whether to enable copy permissions for the website
copyright	Add copyright information after the copied content
enable	Whether to enable adding copyright information
limit_count	Word limit. When the copied text exceeds this limit, copyright information will be added to the copied content

After adding copyright information

Lorem ipsum dolor sit amet, test link consectetur adipiscing elit. Strong text pellentesque ligula commodo viverra vehicula. Italic text at ullamcorper enim. Morbi a euismod nibh. Underline text non elit nisl. Deleted text tristique, sem id condimentum tempus, metus lectus venenatis mauris, sit amet semper lorem felis a eros. Fusce egestas nibh at sagittis auctor. Sed ultricies ac arcu quis molestie. Donec dapibus nunc in nibh egestas, vitae volutpat sem iaculis. Curabitur sem tellus, elementum nec quam id, fermentum laoreet mi. Ut mollis ullamcorper turpis, vitae facilisis velit ultricies sit amet. Etiam laoreet dui odio, id tempus justo tincidunt id. Phasellus scelerisque nunc sed nunc ultricies accumsan.


Author: Jerry
Link: http://localhost:4000/posts/bd3c650b/#Paragraph
Source: Butterfly
Copyright belongs to the author. For commercial reprints, please contact the author for authorization. For non-commercial reprints, please indicate the source.

Word Count

To enable the word count feature, you need to install the hexo-wordcount plugin.

Run npm install hexo-wordcount --save or yarn add hexo-wordcount in the hexo working directory.


wordcount:
  enable: false
  
  post_wordcount: true
  
  min2read: true
  
  total_wordcount: true

Parameter	Explanation
post_wordcount	Display the word count on the article page
min2read	Display the reading time on the article page
total_wordcount	Display the total word count of the website in the sidebar

Visitor Count (UV and PV) by busuanzi

Visit the official website of busuanzi for more information.

Due to the stability issues of busuanzi, there may be occasional access problems. Please be aware.

The visitor count on the article page is implemented through the busuanzi plugin. Some comment systems have their own visitor count feature, which can be enabled in the corresponding comment system configuration and will replace the busuanzi count.

busuanzi:
  site_uv: true
  site_pv: true
  page_pv: true

If you need to modify the CDN link of busuanzi, you can do so through the option in the CDN section of the theme configuration file.

1
2
3

CDN:
  option:
  	busuanzi: xxxxxxxxx

Math

The theme supports two math formula rendering engines, MathJax and KaTeX. You can choose one according to your needs.




math:
  
  
  use:
  per_page: true
  hide_scrollbar: false

Parameter	Explanation
use	Choose the math formula rendering engine, select `mathjax` or `katex`. Leave it empty if you don't need math formulas.
per_page	Whether to load the math formula rendering engine on each page. If set to `false`, you need to add `mathjax: true` or `katex: true` in the article's `Front-matter` to load the math formula rendering engine for that article.
hide_scrollbar	Whether to hide the scrollbar

Do not use MathJax syntax in titles. The TOC may not display MathJax correctly and might show MathJax code instead.

It is recommended to use KaTeX for better results, as introduced below!

To enable MathJax, set use to mathjax.

MathJax configuration file

mathjax:
  
  enableMenu: true
  
  tags: none

Parameter	Explanation
enableMenu	Enable the right-click menu
tags	Choose whether to number equations. `all` for numbering all, `ams` for numbering only equations, `none` for no numbering

Before using MathJax, you need to uninstall Hexo's markdown renderer and then install hexo-renderer-kramed.

Perform the following operations in your Hexo blog directory (not the Butterfly directory):

Install the plugin

1 2	npm uninstall hexo-renderer-marked --save npm install hexo-renderer-kramed --save

Configure the Hexo root directory configuration file

kramed:
  gfm: true
  pedantic: false
  sanitize: false
  tables: true
  breaks: true
  smartLists: true
  smartypants: true

Effect:

Do not use KaTeX syntax in titles. The TOC cannot display KaTeX correctly.

To enable KaTeX, set use to katex.

1
2
3

katex:
  
  copy_tex: false

Parameter	Explanation
copy_tex	Enable the copy KaTeX formula function

You do not need to add katex.min.js to render math equations. Instead, you need to uninstall your previous Hexo markdown renderer and then install other plugins.

Uninstall the marked plugin and install hexo-renderer-markdown-it.

npm un hexo-renderer-marked --save 
npm un hexo-renderer-kramed --save 

npm i hexo-renderer-markdown-it --save 
npm install katex @renbaoshuo/markdown-it-katex

Configure the Hexo root directory _config.yml.

1
2
3

markdown:
  plugins:
    - '@renbaoshuo/markdown-it-katex'

For other parameter configurations, please refer to the KaTeX official website.

Note: This method generates KaTeX without italics.

Uninstall the marked plugin and then install the new hexo-renderer-markdown-it-plus:



npm un hexo-renderer-marked --save



npm un hexo-renderer-kramed --save



npm i @upupming/hexo-renderer-markdown-it-plus --save

Note that hexo-renderer-markdown-it-plus is no longer maintained, so we use @upupming/hexo-renderer-markdown-it-plus. This fork uses @neilsustc/markdown-it-katex, which is also used by the VSCode plugin Markdown All in One, so we can get the latest KaTeX features such as \tag{}.

You can also control KaTeX settings through @neilsustc/markdown-it-katex. All configurable options can be found at https://katex.org/docs/options.html. For example, if you want to disable the lengthy warning messages output by KaTeX on the command line, you can use the following configuration in the root directory _config.yml to set strict to false:

markdown_it_plus:
  plugins:
    - plugin:
      name: '@neilsustc/markdown-it-katex'
      enable: true
      options:
        strict: false

Of course, you can also use this feature to define some commonly used macros.

Since KaTeX is faster and lighter, it does not have as many features as MathJax (such as the right-click menu). For those using MathJax, the theme also includes the copy function of KaTeX.

Search

The theme supports three search methods (algolia_search / local_search / docsearch). You can choose one or multiple search methods.

search:
  
  
  use:
  placeholder:

Parameter	Description
use	Choose the search method you need; leave it empty if not needed
placeholder	Placeholder text in the search box

Remember to run hexo clean

If you use hexo-algoliasearch, make sure to configure the fields parameter with title, permalink, and content.

Install hexo-algolia or hexo-algoliasearch and configure according to their documentation.
Set the use parameter in the theme configuration file to algolia_search.

Additional configuration:


algolia_search:
  
  hitsPerPage: 6

Parameter	Description
hitsPerPage	Number of search results per page

Run Hexo.

Remember to run hexo clean

Install hexo-generator-searchdb or hexo-generator-search and configure according to their documentation.
Set the use parameter in the theme configuration file to local_search.

Additional configuration:


local_search:
  
  preload: false
  
  top_n_per_article: 1
  
  unescape: false
  CDN:

Parameter	Description
preload	Preload search data on page load. If disabled, search data loads when the search button is clicked.
top_n_per_article	Number of matched results to show per article, default is 1
unescape	Unescape HTML strings to readable text
CDN	CDN URL for search data (default is local link)

DocSearch is another search service provided by Algolia. For detailed application and usage, refer to the DocSearch documentation.

Apply for DocSearch and obtain your appId, apiKey, and indexName.
Set the use parameter in the theme configuration file to docsearch.

Additional configuration:

# Docsearch
# https://docsearch.algolia.com/
docsearch:
  appId:
  apiKey:
  indexName:
  option:

Parameter	Description
appId	[Required] Your Algolia application ID
apiKey	[Required] Your Algolia search API key
indexName	[Required] Your Algolia index name
option	[Optional] Additional DocSearch configuration. Refer to the documentation for details.

Only one sharing service can be selected.

The theme supports two sharing methods: sharejs and addtoany.

share:
  
  
  use: sharejs

Parameter	Description
use	Choose the sharing method: `sharejs` or `addtoany`. Leave it empty if sharing is not needed.

If you're not familiar with sharejs, check out its documentation.



sharejs:
  sites: facebook,twitter,wechat,weibo,qq

Refer to addtoany for usage instructions.

1 2	addtoany: item: facebook,twitter,wechat,sina_weibo,facebook_messenger,email,copy_link

The theme supports multiple comment systems. You can choose one according to your preference. You can also select dual comments by configuring two comment systems (the first one will be shown by default).

comments:
  
  
  
  
  use:
  
  text: true
  
  
  lazyload: false
  
  count: false
  
  card_post_count: false

Parameter	Explanation
use	The comment system(s) to use (note: up to two systems, leave empty if not needed). Note: Dual comments cannot be Disqus and Disqusjs together due to shared ID conflicts.
text	Whether to display the comment service name next to the button.
lazyload	Whether to enable lazyload for comments. If enabled, the comment resources will load only when the comment section enters the viewport (comment count will not be displayed if lazyload is enabled).
count	Whether to display the comment count at the top of the post. Livere, Giscus, and Utterances do not support comment count display.
card_post_count	Whether to display the comment count on the homepage post cards. Gitalk, Livere, Giscus, and Utterances do not support comment count display.

1 2	disqus: shortname:

Parameter	Explanation
shortname	Your Disqus shortname. You can create it here.

Similar to Disqus, but can be used to display comments when Disqus is inaccessible in mainland China. Refer to Disqusjs for details.

disqusjs:
  shortname:
  apikey:
  option:

Parameter	Explanation
shortname	Your Disqus shortname. You can create it here.
apikey	Your Disqus API Key. You can create it here.
option	Optional configuration.

Display when Disqus is inaccessible

1 2	livere: uid:

Parameter	Explanation
uid	Your Livere UID. You can create it here.

The Livere UID can be found here:

Follow the Gitalk instructions to obtain your GitHub OAuth application client ID and secret, and check the related configuration instructions.

gitalk:
  client_id:
  client_secret:
  repo:
  owner:
  admin:
  option:

Parameter	Explanation
client_id	GitHub application's client ID.
client_secret	GitHub application's client secret.
repo	The repo to store issues.
owner	The owner of the repo to store issues.
admin	The owner and collaborators of the GitHub repository (users with write permissions to the repository).
option	Optional configuration.

Follow the Valine instructions to configure your LeanCloud application and check the relevant configuration instructions.

valine:
  appId:
  appKey:
  avatar: monsterid
  
  serverURLs:
  bg:
  
  visitor: false
  option:

Parameter	Explanation
appId	The appId of your LeanCloud application.
appKey	The appKey of your LeanCloud application.
avatar	Avatar type, optional values: `''`, `mp`, `identicon`, `monsterid`, `wavatar`, `retro`, `robohash`, `blank`, `404`.
serverURLs	Custom LeanCloud server address. If you use a custom domain in mainland China, please fill in this item, otherwise, leave it empty.
bg	Background image, can be an image URL like `https://example.com/bg.jpg`.
visitor	Whether to display the article read count.
option	Optional configuration.

When visitor is enabled, the article read count on the article page will be provided by Valine, not Busuanzi.

Valine supports custom emojis from v1.4.5. If you need to configure them, set the emojiCDN to your custom emoji CDN.

Also, create a JSON file valine.json in the source/_data/ directory under your Hexo working directory, equivalent to Valine's emojiMaps configuration. The valine.json can be configured as follows:

{
  "tv_doge": "6ea59c827c414b4a2955fe79e0f6fd3dcd515e24.png",
  "tv_親親": "a8111ad55953ef5e3be3327ef94eb4a39d535d06.png",
  "tv_偷笑": "bb690d4107620f1c15cff29509db529a73aee261.png",
  "tv_再見": "180129b8ea851044ce71caf55cc8ce44bd4a4fc8.png",
  "tv_冷漠": "b9cbc755c2b3ee43be07ca13de84e5b699a3f101.png",
  "tv_發怒": "34ba3cd204d5b05fec70ce08fa9fa0dd612409ff.png",
  "tv_發財": "34db290afd2963723c6eb3c4560667db7253a21a.png",
  "tv_可愛": "9e55fd9b500ac4b96613539f1ce2f9499e314ed9.png",
  "tv_吐血": "09dd16a7aa59b77baa1155d47484409624470c77.png",
  "tv_呆": "fe1179ebaa191569b0d31cecafe7a2cd1c951c9d.png",
  "tv_嘔吐": "9f996894a39e282ccf5e66856af49483f81870f3.png",
  "tv_困": "241ee304e44c0af029adceb294399391e4737ef2.png",
  "tv_壞笑": "1f0b87f731a671079842116e0991c91c2c88645a.png",
  "tv_大佬": "093c1e2c490161aca397afc45573c877cdead616.png",
  "tv_大哭": "23269aeb35f99daee28dda129676f6e9ea87934f.png",
  "tv_委屈": "d04dba7b5465779e9755d2ab6f0a897b9b33bb77.png",
  "tv_害羞": "a37683fb5642fa3ddfc7f4e5525fd13e42a2bdb1.png",
  "tv_尷尬": "7cfa62dafc59798a3d3fb262d421eeeff166cfa4.png",
  "tv_微笑": "70dc5c7b56f93eb61bddba11e28fb1d18fddcd4c.png",
  "tv_思考": "90cf159733e558137ed20aa04d09964436f618a1.png",
  "tv_驚嚇": "0d15c7e2ee58e935adc6a7193ee042388adc22af.png"
}

參數	效果
empty（Default）
mp
identicon
monsterid
wavatar
retro
robohash
blank
404

Waline is a comment system derived from Valine that includes backend support. You can consider Waline as "With backend Valine".

Refer to the Waline documentation for detailed configuration.

waline:
  serverURL: 
  bg: 
  pageview: false
  option:

Parameter	Description
serverURL	Waline server address
bg	Background image URL, e.g., `https://example.com/bg.jpg`
pageview	Whether to show article view count
option	Optional configuration

When pageview is enabled, the article view count will be provided by Waline instead of Busuanzi.

Like Gitalk, Utterances is a comment tool based on GitHub issues but with relatively fewer permissions required. Refer to Utterances documentation for details.

utterances:
  repo:
  
  issue_term: pathname
  
  light_theme: github-light
  dark_theme: photon-dark

Parameter	Description
repo	GitHub repository full name, e.g., `owner/repo`
issue_term	Label used to identify issues, options: pathname/url/title/og:title
light_theme	Light theme, options: `github-light`, `github-dark`, `github-dark-orange`, `icy-dark`, `dark-blue`, `photon-dark`
dark_theme	Dark theme, options: `github-light`, `github-dark`, `github-dark-orange`, `icy-dark`, `dark-blue`, `photon-dark`

Facebook Comments is a plugin provided by Facebook, requiring users to log in with Facebook to comment.



facebook_comments:
  app_id:
  
  user_id:
  pageSize: 10
  
  order_by: social
  lang: zh_TW

Parameter	Description
app_id	Facebook App ID, which can be created here
user_id	Optional, Facebook User ID for managing comments
pageSize	Number of comments to display
order_by	Comment sorting method: social/time/reverse_time
lang	Language

Twikoo is a simple, secure, and serverless comment system for static websites, based on Tencent Cloud Development.

For detailed configuration, please refer to the Twikoo documentation.

你只需要把獲取到的 環境ID (envId) 填寫到配置上去就行

twikoo:
  envId:
  region:
  visitor: false
  option:

Parameter	Description
envId	Environment ID
region	Environment region, default is `ap-shanghai`. If your region is different, specify here.
visitor	Whether to display article view count
option	Optional configuration

When visitor is enabled, the article view count will be provided by Twikoo instead of Busuanzi.

A comment system based on GitHub Discussions.



giscus:
  repo:
  repo_id:
  category_id:
  theme:
    light: light
    dark: dark
  option:

Parameter	Description
repo	GitHub repository full name, e.g., `owner/repo`
repo_id	GitHub repository ID
category_id	GitHub repository category ID
option	Optional configuration

Refer to the Giscus documentation for details.

Remark42 is a comment system that only supports self-hosting.

For detailed setup, refer to Installation | Remark42.

remark42:
  host: 
  siteId: 
  option:

Parameter	Description
host	Your Host URL
siteId	Your Site ID
option	Optional configuration

Artalk is a comment system that only supports self-hosting.

For detailed setup, refer to Artalk | Self-hosted Comment System.

artalk:
  server:
  site:
  
  visitor: false
  option:

Parameter	Description
server	Your Server URL
site	Your Site ID
visitor	Whether to display article view count
option	Optional configuration

When visitor is enabled, the article view count will be provided by Artalk instead of Busuanzi.

Online Chat

The theme includes several online chat tools. You can choose to enable one to facilitate communication with your visitors.

chat:
  
  
  use:
  
  
  rightside_button: false
  
  button_hide_show: false

Parameter	Description
use	Choose the chat tool to use, options are `chatra`/`tidio`/`crisp`
rightside_button	Enable the chat button at the bottom right corner
button_hide_show	Hide chat button when scrolling down, show when scrolling up

These tools provide a button to open/close the chat window. The theme also provides a custom button that will appear in the bottom right corner. Just enable the rightside_button.

To avoid affecting user experience, the theme offers a button_hide_show configuration. Set to true to show the chat button only when scrolling up.

To enable Chatra, set the chat configuration use to chatra.

Configure Chatra by getting the Public key.

Open Chatra and sign up.
Find the Public key in Preferences.



chatra:
  id: xxxxxxxx

You can customize Chatra's style in Chat Widget.

To enable Tidio, set the chat configuration use to tidio.

Configure Tidio by getting the Public key.

Open Tidio and sign up.
Find the Public key in Preferences > Developer.



tidio:
  public_key: XXXX

You can customize Tidio's style in Channels.

To enable Crisp, set the chat configuration use to crisp.

Configure Crisp by getting the Website ID.

Open Crisp and sign up.
Find the Website ID.



crisp:
  website_id: xxxxxxxx

Analytics

Log in to the Baidu Analytics official website.
Locate your Baidu Analytics code.

Modify the theme configuration file:

1	baidu_analytics: your_code

Log in to the Google Analytics official website.
Find your Google Analytics tracking ID.

Modify the theme configuration file:

1	google_analytics: your_code

Log in to the Cloudflare Analytics official website.
Locate the JavaScript Snippet.
Find your token.

Modify the theme configuration file:
1
2
3

cloudflare_analytics:

Log in to the Clarity official website.
Create a PROJECT.
Find your ID.

Modify the theme configuration file:
1
2
3

microsoft_clarity:

The theme integrates Google Ads (Auto Ads).

google_adsense:
  enable: true
  auto_ads: true
  js: https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js
  client: 
  enable_page_level_ads: true

The theme reserves three spots for inserting ads: after every three articles on the homepage, after the aside announcement, and after the post donation section. Fill in the HTML code in the corresponding position.

ad:
  index:
  aside:
  post:

例如:

index: <ins class="adsbygoogle" style="display:block" data-ad-format="fluid" data-ad-layout-key="xxxxxxxxxxxx" data-ad-client="ca-pub-xxxxxxxxxx" data-ad-slot="xxxxxxxxxx"></ins><script>(adsbygoogle=window.adsbygoogle||[]).push({})</script>

Website Verification

If you need search engines to index your site, you may need to log in to the corresponding search engine management platform for submission. Verification codes can be obtained from each management platform.

site_verification:

Beautify / Effect

Custom Theme Colors

You can modify most UI colors.

Edit the theme configuration file, for example:

Color values must be enclosed in double quotes, like "#000" instead of #000. Otherwise, an error will occur during the build process!

theme_color:
  enable: true
  main: '#49B1F5'
  paginator: '#00c4b6'
  button_hover: '#FF7242'
  text_selection: '#00c4b6'
  link_color: '#99a9bf'
  meta_color: '#858585'
  hr_color: '#A4D8FA'
  code_foreground: '#F47466'
  code_background: 'rgba(27, 31, 35, .05)'
  toc_color: '#00c4b6'
  blockquote_padding_color: '#49b1f5'
  blockquote_background_color: '#49b1f5'
  scrollbar_color: '#49b1f5'
  meta_theme_color_light: 'ffffff'
  meta_theme_color_dark: '#0d0d0d'

Parameter	Description
main	Main theme color
paginator	Paginator color
button_hover	Button hover color
text_selection	Text selection color
link_color	Link color
meta_color	Article metadata color
hr_color	Horizontal rule color
code_foreground	Code foreground color
code_background	Code background color
toc_color	Table of contents color
blockquote_padding_color	Blockquote padding color
blockquote_background_color	Blockquote background color
scrollbar_color	Scrollbar color
meta_theme_color_light	Light mode theme color
meta_theme_color_dark	Dark mode theme color

Justify Text Alignment

You can set text to be justified, except for the last line.

1 2	text_align_justify: true

text_align_justify: false

Black Mask

To avoid overly bright images making text unreadable, a black mask is added to header and footer by default.


mask:
  header: true
  footer: true

Page Load Animation (Preloader)

When entering a webpage, due to loading speed issues, the top_img image may appear fragmented, or the webpage may not load fully, resulting in a wait time. Enabling the preloader will show a loading animation, which will disappear once the page is fully loaded.

The theme supports the loading animation of pace.js, see pace.js for details.


preloader:
  enable: false
  
  
  
  source: 1
  
  pace_css_url:

Page Beautification

It changes the styles of ol, ul, h1-h5.

field configuration applies to:

post Applies only to the post page
site Applies to the entire site


beautify:
  enable: true
  field: site 
  title-prefix-icon: '\f0c1'
  title-prefix-icon-color: '#F47466'

Parameter	Description
enable	Enable beautification
field	Area to be beautified
title-prefix-icon	Prefix icon for titles
title-prefix-icon-color	Color of the prefix icon

title-prefix-icon is the Unicode value of the fontawesome icon.

Custom Fonts and Font Sizes

Global Fonts

You can set the font-family for the entire site.

If no configuration is needed, leave it empty.



font:
  global-font-size:
  code-font-size:
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Lato, Roboto, "PingFang SC", "Microsoft JhengHei", "Microsoft YaHei", sans-serif
  code-font-family: consolas, Menlo, "PingFang SC", "Microsoft JhengHei", "Microsoft YaHei", sans-serif

Parameter	Description
global-font-size	Global font size
code-font-size	Code font size
font-family	Global font family
code-font-family	Code font family

Blog Title Font

You can set the font-family for the site title and subtitle.
If no configuration is needed, leave it empty.
If no web font is needed, leave font_link empty.



blog_title_font:
  font_link: https://fonts.googleapis.com/css?family=Titillium+Web&display=swap
  font-family: Titillium Web, 'PingFang SC', 'Hiragino Sans GB', 'Microsoft JhengHei', 'Microsoft YaHei', sans-serif

Parameter	Description
font_link	Link to the web font
font-family	Font family for the site title

Typing Effect

Typing effect activate-power-mode.



activate_power_mode:
  enable: true
  colorful: true 
  shake: true 
  mobile: false

Parameter	Description
enable	Enable typing effect
colorful	Enable particle animation
shake	Enable shake effect
mobile	Enable typing effect on mobile

Background Effects

Beautiful ribbon background, can be set to change ribbon on each refresh or on each click

canvas_ribbon:
  enable: false
  
  size: 150
  
  alpha: 0.6
  zIndex: -1
  click_to_change: false
  mobile: false

Parameter	Description
enable	Enable ribbon effect
size	Size of the ribbon
alpha	Opacity of the ribbon
zIndex	z-index of the ribbon
click_to_change	Change ribbon on click
mobile	Show ribbon on mobile

For more configuration, refer to canvas_ribbon

Beautiful ribbon background that floats

1
2
3

canvas_fluttering_ribbon:
  enable: true
  mobile: false

canvas_nest:
  enable: false
  
  color: '0,0,255'
  
  opacity: 0.7
  
  zIndex: -1
  
  count: 99
  mobile: false

Parameter	Description
enable	Enable nest effect
color	Color of the lines
opacity	Opacity of the lines
zIndex	z-index of the lines
count	Number of lines
mobile	Show effect on mobile

Mouse Click Effects

fireworks:
  enable: true
  zIndex: 9999 
  mobile: false

Parameter	Description
enable	Enable fireworks effect
zIndex	z-index of fireworks (`-1` means behind / `9999` means in front)
mobile	Show fireworks on mobile


click_heart:
  enable: true
  mobile: false


ClickShowText:
  enable: false
  text:
    - I
    - LOVE
    - YOU
  fontSize: 15px
  random: false 
  mobile: false

Parameter	Description
enable	Enable text effect
text	Text content
fontSize	Font size
random	Randomize text display
mobile	Show text on mobile

If you do not want to add lightbox for a specific image, use HTML format to reference the image and add no-lightbox class name to the image





lightbox:

You can configure fancybox or medium_zoom to enable lightbox.
Leave it empty if no lightbox is needed.

Tag Plugins

For details, see Tag Plugins

Mermaid

The theme supports Mermaid.js, which can be used to draw flowcharts, sequence diagrams, etc., in articles.



mermaid:
  enable: true
  
  code_write: true
  
  theme:
    light: default
    dark: dark

Writing Methods

The theme supports two writing methods

Tag Plugin

You can use the tag plugin method to use Mermaid.js For details, see Tag Plugins

Code Block Writing

You can use the code block method to use Mermaid.js

Hexo version needs to be 7.0 or above

Add exclude_languages: ['mermaid'] to the Hexo configuration file

syntax_highlighter: 'highlight.js'
highlight:
  line_number: true
  auto_detect: false
  tab_replace: ''
  wrap: true
  hljs: false
  exclude_languages: ['mermaid']
prismjs:
  preprocess: true
  line_number: true
  tab_replace: ''
  exclude_languages: ['mermaid']

Set code_write to true in the Mermaid configuration of the Butterfly theme

Demo

graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;

Pjax

When a user clicks a link, the parts of the page that need to be updated are done so via Ajax, and then the browser's URL is modified using HTML5's pushState.

This avoids reloading identical resources (css/js), thereby improving page load speed.

pjax:
  enable: false
  
  exclude:

For some third-party plugins, Pjax may not be supported.
You can add web pages to the exclude list to exempt them from Pjax.
Clicking these pages will reload the website.

After using Pjax, some custom JavaScript may become ineffective and need to be re-invoked when navigating pages. Refer to the Pjax documentation.
Also, some specific pages' js/css will be loaded on all pages after using Pjax.

Snackbar - Toast Notification

Enable the Snackbar based on personal preference.




snackbar:
  enable: false
  position: bottom-left
  
  bg_light: '#49b1f5'
  bg_dark: '#1f1f1f'

Instantpage

When the mouse hovers over a link for more than 65 milliseconds, Instantpage preloads the link, improving access speed.

1
2
3



instantpage: true

PWA

To add PWA features to Butterfly, you need to follow these steps:

Open the hexo working directory.
Run npm install hexo-offline --save or yarn add hexo-offline.
Create a file named hexo-offline.config.cjs in the hexo directory and add the following content:


module.exports = {
  globPatterns: ['**/*.{js,html,css,png,jpg,gif,svg,webp,eot,ttf,woff,woff2}'],
  
  globDirectory: 'public',
  swDest: 'public/service-worker.js',
  maximumFileSizeToCacheInBytes: 10485760, 
  skipWaiting: true,
  clientsClaim: true,
  runtimeCaching: [ 
    
    {
      urlPattern: /^https:\/\/cdn\.example\.com\/.*/, 
      handler: 'CacheFirst'
    }
  ]
}

For more details, refer to the official hexo-offline documentation.

Enable the PWA option in the theme configuration file.

pwa:
  enable: true
  manifest: /img/pwa/manifest.json
  apple_touch_icon: /img/pwa/apple-touch-icon.png
  favicon_32_32: /img/pwa/32.png
  favicon_16_16: /img/pwa/16.png
  mask_icon: /img/pwa/safari-pinned-tab.svg

Create a manifest.json file in the source/ directory.

{
    "name": "string",
    "short_name": "Junzhou",
    "theme_color": "#49b1f5",
    "background_color": "#49b1f5",
    "display": "standalone",
    "scope": "/",
    "start_url": "/",
    "icons": [
        {
          "src": "images/pwaicons/36.png",
          "sizes": "36x36",
          "type": "image/png"
        },
        {
            "src": "images/pwaicons/48.png",
          "sizes": "48x48",
          "type": "image/png"
        },
        {
          "src": "images/pwaicons/72.png",
          "sizes": "72x72",
          "type": "image/png"
        },
        {
          "src": "images/pwaicons/96.png",
          "sizes": "96x96",
          "type": "image/png"
        },
        {
          "src": "images/pwaicons/144.png",
          "sizes": "144x144",
          "type": "image/png"
        },
        {
          "src": "images/pwaicons/192.png",
          "sizes": "192x192",
          "type": "image/png"
        },
        {
            "src": "images/pwaicons/512.png",
            "sizes": "512x512",
            "type": "image/png"
          }
      ],
      "splash_pages": null
  }

You can also quickly create a manifest.json using the Web App Manifest. (Web App Manifest requires at least one 512x512 pixel icon).

Use the Chrome Lighthouse plugin to check if the PWA configuration is effective and correct.
- Open the blog page.
- Launch the Lighthouse plugin (Lighthouse plugin requires at least one 512x512 pixel icon).

For more information on PWA (Progressive Web Apps), refer to Google Tools for Web Developers.

Open Graph

Add some meta data such as thumbnails, titles, and dates in the head. When you share a webpage on certain platforms, the platform will read the Open Graph content and display information like thumbnails and titles.



Open_Graph_meta:
  enable: true
  option:

CSS Prefixes

Some CSS properties are not supported by all browsers and need corresponding prefixes to be effective.

Enabling css_prefix will automatically add prefixes to some CSS properties (increasing the size by 20%).

1 2	css_prefix: true

Inject

Supported from version 2.3.0 and above

If you want to add extra JavaScript, CSS, meta tags, etc., you can add them in inject. This supports adding to the head (before the </body> tag) and the bottom (before the </html> tag).

Note: Add the content in standard HTML format.

For example:

inject:
  head:
  	- <link rel="stylesheet" href="/self.css">
  bottom:
  	- <script src="xxxx"></script>

Note: If your site root directory is not '/', you need to include your root directory when using local images.
For example: If your site is https://yoursite.com/blog and you want to reference css/xx.css, set it as <link rel="stylesheet" href="/blog/css/xx.css">.

CDN

The last part of the configuration file is CDN, which includes files referenced by the theme. You can configure the CDN yourself (please do not modify unless necessary, and confirm that the links are accessible after configuration).



CDN:
  
  
  
  
  internal_provider: local
  third_party_provider: jsdelivr

  
  version: false

  
  
  custom_format:

  option:

Parameter	Explanation
internal_provider	Internal files of the theme Options: local/jsdelivr/unpkg/cdnjs/custom local for local loading, custom for custom format, needs to configure `custom_format` Note: If using the Dev version, it can only be set to local
third_party_provider	Third-party files Options: local/jsdelivr/unpkg/cdnjs/custom local for local loading, custom for custom format, needs to configure `custom_format` Note: If you choose local, you need to install the `hexo-butterfly-extjs` plugin
version	true/false to add the specified version number to the CDN
custom_format	Custom format
option	You can replace some files here, which will override the original configuration

version

To modify the version number, you can change the version in the 'plugins.yml' file in the theme directory.

Please ensure that the version number you modify is included in the CDN you use.

custom_format

Provides the following parameters:

Parameter	Explanation
name	Package name on npm
file	File path on npm
min_file	Minified file path on npm
cdnjs_name	Package name on cdnjs
cdnjs_file	File path on cdnjs
min_cdnjs_file	Minified file path on cdnjs
version	Plugin version number

Partial list of available third-party CDNs:

Please ensure that the CDN you choose includes the third-party plugins used by the theme.

Provider	Format	Remarks
Staticfile (Qiniu Cloud)	https://cdn.staticfile.org/${cdnjs_name}/${version}/${min_cdnjs_file}	Sync with cdnjs
BootCDN	https://cdn.bootcdn.net/ajax/libs/${cdnjs_name}/${version}/${min_cdnjs_file}	Sync with cdnjs
Baomitu (360)	Latest version: https://lib.baomitu.com/${cdnjs_name}/latest/${min_cdnjs_file} Specified version: https://lib.baomitu.com/${cdnjs_name}/${version}/${min_cdnjs_file}	Sync with cdnjs
Elemecdn	Latest version: https://npm.elemecdn.com/${name}@latest/${file} Specified version: https://npm.elemecdn.com/${name}@${version}/${file}	Sync with npm

⚔️ Butterfly document - Tag Plugins

推荐订阅源

Butterfly

Quick Read of Configuration Files

Language

Code Blocks

Code Highlight Theme

Code Block Expand/Collapse

Code Word Wrap

Code Height Limit

Image Settings

Avatar

Top Image

Website Background

Article Cover

Page Meta Display

Home Page

Home Page Top Image Size

Website Subtitle

Home Page Card Layout

Home Page Article Excerpts

Article Page

TOC (Table of Contents)

Configuring for Specific Articles

Article Copyright

Article Donations/Sponsorship

Article Edit Button

Related Articles

Article Pagination Buttons

Outdated Article Reminder

Blog Start Year

Aside

Aside Configuration

Custom Add Aside Widget

Bottom Right Buttons

Button Position

Simplified and Traditional Chinese Conversion

Reading Mode

Dark Mode

Scroll Status Percentage

Button Sorting

Global Configuration

Page Anchors

Image Captions

Copy Configuration

Word Count

Visitor Count (UV and PV) by busuanzi

Math

Search

Online Chat

Analytics

Advertisements

Website Verification

Beautify / Effect

Custom Theme Colors

Justify Text Alignment

Black Mask

Page Load Animation (Preloader)

Page Beautification

Custom Fonts and Font Sizes

Global Fonts

Blog Title Font

Typing Effect

Background Effects

Mouse Click Effects

Lightbox

Tag Plugins

Mermaid

Writing Methods

Tag Plugin

Code Block Writing

Pjax

Snackbar - Toast Notification

Instantpage

PWA

Open Graph

CSS Prefixes

Inject

CDN

version

custom_format