Butterfly document - Theme Configuration Part 1

Language

Modify the site configuration file _config.yml.

The default language is set to English (en).

The theme supports three languages:

• default (English)
• zh-CN (Simplified Chinese)
• zh-TW (Traditional Chinese)

Website Information

To modify various data on the website, such as the title, subtitle, and email address, please edit the _config.yml file located in the root directory of your blog.

Navigation Bar Settings

Parameter Configuration

In the theme configuration file, you can find the following parameters for setting up the navigation bar:

1
2
3
4

nav:
  logo: #image
  display_title: true
  fixed: false # fixed navigation bar

Menu/Directory

To modify the navigation menu, edit the "Theme Configuration File" as follows:

1
2
3
4
5
6
7
8
9

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

Each item in the menu is specified with a format of /xxx/ || icon_name. If you don't want to display an icon, you can omit the icon_name.

The default behavior for subdirectories is to be expanded. If you want them to be hidden, you can add 'hide' to the configuration of the subdirectory

1
2
3

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

Note: The navigation text can be customized as desired.

For example:

1
2
3
4
5
6
7
8
9
10
11

menu:
  首頁: / || fas fa-home
  時間軸: /archives/ || fas fa-archive
  標籤: /tags/ || fas fa-tags
  分類: /categories/ || fas fa-folder-open
  清單||fa fa-heartbeat:
    音樂: /music/ || fas fa-music
    照片: /Gallery/ || fas fa-images
    電影: /movies/ || fas fa-video
  友鏈: /link/ || fas fa-link
  關於: /about/ || fas fa-heart

Code Blocks

Code Highlight Themes

Code Copy

The theme supports code copy functionality.

To enable code copy, edit the theme_config file.

1

highlight_copy: true

Code Blocks Expansion/Collapse

By default, code blocks are automatically expanded. You can choose to have all code blocks in a collapsed state, and users can click the '>' symbol to expand the code.

• true: All code blocks are not expanded and need to be opened by clicking '>'.
• false: Code blocks are expanded, and there is a '>' button to collapse them.
• none: The '>' button is not displayed.

To modify the behavior, edit the theme_config file.

1

highlight_shrink: true # Code blocks are not expanded, need to click '>' to open.

highlight_shrink: true

highlight_shrink: false

highlight_shrink: none

Code Line Wrapping

By default, Hexo does not automatically wrap lines in code blocks during compilation. If you don't want horizontal scrollbars in the code block area, you can consider enabling this feature.

To enable line wrapping, edit the theme_config file.

1

code_word_wrap: true

If you are using the highlight renderer, you need to find the Hexo configuration file _config.yml and change line_number to false:

1
2
3
4
5

highlight:
  enable: true
  line_number: false # <- Change this line
  auto_detect: false
  tab_replace:

If you are using the prismjs renderer, you need to find the Hexo configuration file _config.yml and change line_number to false:

1
2
3
4
5

prismjs:
  enable: false
  preprocess: true
  line_number: false # <- Change this line
  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 set a limit on the code block height, and the overflow will be hidden, with an expand button displayed.

1

highlight_height_limit: false # unit: px

Note:

1. The unit is px, simply add the number, e.g., 200.
2. The actual height limit is highlight_height_limit + 30 px. An extra 30px is added to prevent the expand button from appearing when the code's height is only slightly greater than the highlight_height_limit.
3. Does not apply to hidden code blocks (CSS set to display: none).

Social Settings

Butterfly supports Font Awesome v6 icons.

The format for writing 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 in the image below:

PC:

Mobile:

Avatar

Edit the theme_config file

1
2
3

avatar:
  img: /img/avatar.png
  effect: true # spinning effect for the avatar

Top Image

Values in the configuration:

For other pages (tags/categories/custom pages) and article pages, please set front-matter in the corresponding md file to configure top_img.

All top_img configurations above support the following values:

Versions below 3.2.0 only support

• Empty, true, and false - display the default color
• img link - display the configured image

tag_per_img and category_per_img are newly added in version 3.2.0, allowing separate configurations for tags and categories.

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

1
2
3
4
5
6
7

tag_per_img:
  aplayer: https://xxxxxx.png
  android: ddddddd.png
  
category_per_img:
  隨想: hdhdh.png
  推薦: ddjdjdjd.png

top_img: false

top_img: orange

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

Article Cover

In the markdown file of an article, you can add a cover field in the Front-matter section and provide the URL of the image you want to display as the cover.

If you don't configure the cover field, you can set it to display the default cover.

If you don't want to display the cover on the homepage, you can set it to false.

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

To modify the theme configuration file, use the following YAML structure:

1
2
3
4
5
6
7
8
9
10

cover:
  # Whether to display the article cover on the homepage
  index_enable: true
  aside_enable: true
  archives_enable: true
  # The position of the cover display on the homepage
  # Three possible values: left, right, both
  position: both
  # Default cover to display when no specific cover is configured
  default_cover: 

Explanation of parameters:

When configuring multiple cover images, a random image will be selected as the cover. In this case, the configuration should be:

1
2
3
4

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

left

right

both

Meta Display

The post_meta option is used to display relevant information about the articles.

To modify the theme configuration file, use the following YAML structure:

1
2
3
4
5
6
7
8
9
10
11
12
13

post_meta:
  page:
    date_type: both # created or updated or both, display creation date or update date or both on the homepage
    date_format: relative # date/relative, display the date or relative date
    categories: true # true or false, whether to display categories on the homepage
    tags: true # true or false, whether to display tags on the homepage
    label: true # true or false, whether to display descriptive text
  post:
    date_type: both # created or updated or both, display creation date or update date or both on the article page
    date_format: relative # date/relative, display the date or relative date
    categories: true # true or false, whether to display categories on the article page
    tags: true # true or false, whether to display tags on the article page
    label: true # true or false, whether to display descriptive text

Explanation of parameters:

• For the homepage (page):

  • date_type: Display the creation date (created), update date (updated), or both (both) on the homepage.
  • date_format: Display the date (date) or a relative date (relative) on the homepage.
  • categories: Whether to display the categories on the homepage (true or false).
  • tags: Whether to display the tags on the homepage (true or false).
  • label: Whether to display descriptive text on the homepage (true or false).

• For the article page (post):

  • date_type: Display the creation date (created), update date (updated), or both (both) on the article page.
  • date_format: Display the date (date) or a relative date (relative) on the article page.
  • categories: Whether to display the categories on the article page (true or false).
  • tags: Whether to display the tags on the article page (true or false).
  • label: Whether to display descriptive text on the article page (true or false).

Homepage

Article Page

The date_format parameter was introduced in version 3.2.0, allowing you to configure whether to display specific dates or relative dates.

Relative Time:

Full Date:

Homepage Article Excerpt (Auto Excerpt and Article Description)

Due to the theme's UI design, the "Homepage Article Excerpt" supports only "Auto Excerpt" and "Article Description."

In butterfly, there are four options available:

1. description: Only display the article description.
2. both: Prioritize displaying the article description; if there is no description configured, it will display the auto excerpt content.
3. auto_excerpt: Only display the auto excerpt.
4. false: Do not display the article content.

To configure, modify the theme configuration file:

1
2
3

index_post_content:
  method: 3
  length: 500 # If you set the method to 2 or 3, you need to configure the length

To add the description in the front-matter:

Page Anchors

When you enable page anchors, the page links will update according to the header ID when scrolling. (Note: Each update will create a new history entry. So if an article has many anchors, there will be many history entries in the browser.)

To configure, modify the theme configuration file:

1
2
3
4
5
6
7

# anchor
# When you scroll in a post, the URL will update according to the header ID.
anchor:
  # when you scroll, the URL will update according to header id.
  auto_update: false
  # Click the headline to scroll and update the anchor
  click_to_scroll: false

Image Captions

You can enable the display of Figcaption text for images.

The priority for displaying the caption is as follows: image title attribute first, and then the alt attribute.

To configure, modify the theme configuration file:

1

photofigcaption: true

Copy Settings

You can configure whether users can copy content from your website and whether the copied content should have copyright information.

To configure, modify the theme configuration file:

1
2
3
4
5
6
7

# copy settings
# copyright: Add the copyright information after copied content
copy:
  enable: true
  copyright:
    enable: true
    limit_count: 50

After enabling the option, when users copy content from your website, the copied text will have the following copyright information added at the end:

1
2
3
4
5
6
7

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.

作者: Jerry
連結: http://localhost:4000/posts/bd3c650b/#Paragraph
來源: Butterfly
著作權歸作者所有。商業轉載請聯絡作者獲得授權，非商業轉載請註明出處。

Note that the specific text may vary based on your configuration and settings.

Article Page Configuration

Article Copyright

You can display the copyright and license information for your blog posts.

To set up the article copyright, modify the theme configuration file:

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/

Explanation of the attributes:

Starting from Hexo 4.1, URLs are decoded by default, which may cause Chinese URLs to be decoded. You can set decode: true to display Chinese URLs properly.

If there are articles (e.g., reposted articles) that don't require showing copyright information, you can set copyright: false in the article's Front-matter.

1

copyright: false

Starting from version 3.0.0, you can also set individual copyright information for specific articles in their Front-matter:

1
2
3
4
5
6
7
8
9

---
title: My Article
date: 2023-06-30
tags: [example, hexo, theme]
copyright_author: Author Name
copyright_author_href: https://authorwebsite.com
copyright_url: https://licensewebsite.com
copyright_info: This article is copyrighted by Author Name. If you reproduce it, please credit the original author.
---

This allows you to have different copyright information for different articles.

Article Rewards

You can add a reward button at the end of each article, along with the relevant QR codes that users can use for donations.
If you don't provide a QR code, you can configure an icon image and add the corresponding donation link. When users click on the image, they will be redirected to the specified link.

To set up article rewards, modify the theme configuration file:

1
2
3
4
5
6
7
8
9
10

reward:
  enable: true
  text:
  QR_code:
    - img: /img/wechat.jpg
      link:
      text: 微信
    - img: /img/alipay.jpg
      link:
      text: 支付寶

Explanation of the attributes:

You can configure multiple reward options by adding more entries to the QR_code list. If you don't want to provide a link, you can leave the link attribute empty, and the image will act as a direct link.

Table of Contents (TOC)

The theme provides a Table of Contents (TOC) on the article page to display the table of contents.

To configure the TOC, you can modify the theme configuration file:

1
2
3
4
5
6
7

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

Explanation of the attributes:

Toc PC

Toc Mobile

style_simple: true

Configuring for Specific Posts

To configure the Table of Contents (TOC) for a specific post, add toc_number and toc in the front matter section of your Markdown file and set it to either true or false.

The theme will first check if the Markdown Front Matter of the article contains these configurations. If they are present, the theme will use the Front Matter configurations. Otherwise, it will use the configurations specified in the theme configuration file.

Example:

1
2
3
4
5
6
7
8

---
title: Example Post
date: 2023-06-30
toc: true
toc_number: true
---

Your post content goes here.

Related Posts

The related posts are recommended based on the weight of the article tags.

Modify the theme configuration file:

1
2
3
4

related_post:
  enable: true
  limit: 6 # Number of recommended posts to display
  date_type: created # or created or updated to show the creation date or update date of the article

• enable: Set to true to enable the display of related posts.
• limit: The number of recommended posts to display.
• date_type: Set to created or updated to display the creation date or update date of the article in the related posts section.

Article Expiry Reminder

You can configure whether to display an article expiry reminder based on the update time.

1
2
3
4
5
6
7
8

# Displays outdated notice for a post (文章過期提醒)
noticeOutdate:
  enable: true
  style: flat # style: simple/flat
  limit_day: 365 # When will it be shown
  position: top # position: top/bottom
  message_prev: It has been
  message_next: days since the last update, the content of the article may be outdated.

• limit_day: The number of days after which the expiry reminder will be shown based on the update time.
• message_prev: The text before the number of days.
• message_next: The text after the number of days.

style: flat

style: simple

Article Editing Button

Display an editing button next to the article title that redirects to the corresponding link.

1
2
3
4
5
6
7

# Post edit
# Easily browse and edit blog source code online.
post_edit:
  enable: false
  # url: https://github.com/user-name/repo-name/edit/branch-name/subdirectory-name/
  # For example: https://github.com/jerryc127/butterfly.js.org/edit/main/source/
  url:

Post Pagination Buttons

You can configure the logic for post pagination or disable the pagination display altogether using the following settings:

1
2
3
4
5
6

# post_pagination (pagination)
# value: 1 || 2 || false
# 1: The 'next post' will link to an older post
# 2: The 'next post' will link to a newer post
# false: Disable pagination
post_pagination: false

Explanation of parameters:

Footer Settings

Blog Year

The since option is used to display the starting year of your website. It will be shown at the bottom of the page as part of the footer.

To display the starting year in the footer, modify the theme configuration file as follows:

1
2
3
4

footer:
  owner:
    enable: true
    since: 2018

Custom Footer Text

The custom_text option allows you to add custom text to the footer of your website. You can use this option to add statements, declarations, or any other custom text you want. It supports HTML formatting.

To add custom text to the footer, modify the theme configuration file as follows:

1

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

This will display the custom text in the footer, as shown in the image below:

If you need to include ICP (Internet Content Provider) information for certain regions that require it, you can also add it to the custom_text option:

1

custom_text: <a href="icp_link"><img class="icp-icon" src="icp_image"><span>备案号：xxxxxx</span></a>

In this example, replace icp_link with the actual ICP link and icp_image with the image representing your ICP registration.

Aside Settings

Aside Layout

You can customize which items to display in the aside, decide their position, and even hide the sidebar if needed.

Modify the theme configuration file to make changes.

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
47
48
49
50
51
52
53
54
55

aside:
  enable: true
  hide: false
  button: true
  mobile: true # display on mobile
  position: right # left or 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 # if set 0 will show all
    sort: date # date or updated
    sort_order: # Don't modify the setting unless you know how it works
  card_categories:
    enable: true
    limit: 8 # if set 0 will show all
    expand: none # none/true/false
    sort_order: # Don't modify the setting unless you know how it works
  card_tags:
    enable: true
    limit: 40 # if set 0 will show all
    color: false
    orderby: random # Order of tags, random/name/length
    order: 1 # Sort of order. 1, asc for ascending; -1, desc for descending
    sort_order: # Don't modify the setting unless you know how it works
  card_archives:
    enable: true
    type: monthly # yearly or monthly
    format: MMMM YYYY # eg: YYYY年MM月
    order: -1 # Sort of order. 1, asc for ascending; -1, desc for descending
    limit: 8 # if set 0 will show all
    sort_order: # Don't modify the setting unless you know how it works
  card_webinfo:
    enable: true
    post_count: true
    last_push_date: true
    sort_order: # Don't modify the setting unless you know how it works
  card_post_series:
    enable: true
    orderBy: 'date' # Order by title or date
    order: -1 # Sort of order. 1, asc for ascending; -1, desc for descending

position: left

position: right

card_tags color: false

card_tags color: true

aside button

Visitor Count (busuanzi) - UV and PV

Visit the official website of busuanzi for more information.

Modify the theme configuration file as follows:

1
2
3
4

busuanzi:
  site_uv: true
  site_pv: true
  page_pv: true

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

1
2
3

CDN:
  option:
  	busuanzi: xxxxxxxxx

Runtimeshow

Displays the running time of the website.

Modify the theme configuration file as follows:

1
2
3
4
5
6

runtimeshow:
  enable: true
  publish_date: 6/7/2018 00:00:00  
  ## Website launch date
  # Format: MM/DD/YYYY HH:mm:ss
  # It can also be written as YYYY/MM/DD HH:mm:ss

Newest Comments

Supported from version 3.1.0

To display the newest comments section in the sidebar, modify the theme configuration file as follows:

1
2
3
4
5
6
7

# Aside widget - Newest Comments
newest_comments:
  enable: true
  sort_order: # Don't modify the setting unless you know how it works
  limit: 6
  storage: 10 # unit: mins, save data to localStorage
  avatar: true

Explanation of some configurations:

Demo

Custom Add Aside Widget

Bottom Right Button

Simplified-Traditional Chinese Conversion

Enable the simplified-traditional Chinese character conversion feature.

A button for simplified-traditional Chinese character conversion will be displayed in the bottom right corner.

To enable this feature, modify the theme configuration file:

1
2
3
4
5
6
7
8
9
10
11
12

translate:
  enable: true
  # Default text displayed on the button (if the website is in simplified Chinese, set to 'default: 繁')
  default: 簡
  # Default language for the website, 1: Traditional Chinese, 2: Simplified Chinese
  defaultEncoding: 1
  # Translation delay time, if required, set the delay time for translation, e.g., 100 means 100ms, default is 0
  translateDelay: 0
  # Text displayed on the button when the content is in simplified Chinese
  msgToTraditionalChinese: "繁"
  # Text displayed on the button when the content is in traditional Chinese
  msgToSimplifiedChinese: "簡"

Simplified Chinese

Traditional Chinese

Read Mode

In Read Mode, the theme will remove all content except for the article, providing a distraction-free reading experience.

The Read Mode button will appear only on the article pages, located in the bottom right corner.

To enable Read Mode, modify the theme configuration file:

1

readmode: true

When enabled, users will be able to activate the Read Mode by clicking on the button while reading an article.

Dark Mode

In the theme configuration file, you can enable the dark mode feature and customize its behavior using the following parameters:

1
2
3
4
5
6
7
8
9

# dark mode
darkmode:
  enable: true
  # Display the dark mode toggle button in the bottom right corner
  button: true
  autoChangeMode: false
  # Set the light mode time. The value is between 0 and 24. If not set, the default value is 6 and 18
  start: # 8
  end: # 22

The theme will display a night mode toggle button in the bottom right corner as shown in the image above.

Scroll Percentage

In the theme config file

1
2

# show scroll percent in scroll-to-top button
rightside_scroll_percent: true

Button Sorting

1
2
3
4
5
6
7

# Don't modify the following settings unless you know how they work
# Choose: readmode,translate,darkmode,hideAside,toc,chat,comment
# Don't repeat
rightside_item_order:
  enable: false
  hide: # readmode,translate,darkmode,hideAside
  show: # toc,chat,comment

Tag Plugins

Note (Bootstrap Callout)

1
2
3
4
5
6
7
8
9
10
11
12

note:
  # Note tag style values:
  #  - simple    bs-callout old alert style. Default.
  #  - modern    bs-callout new (v2-v3) alert style.
  #  - flat      flat callout style with background, like on Mozilla or StackOverflow.
  #  - disabled  disable all CSS styles import of note tag.
  style: simple
  icons: false
  border_radius: 3
  # Offset lighter of background in % for modern and flat styles (modern: -12 | 12; flat: -18 | 6).
  # Offset also applied to label tag variables. This option can work with disabled note tag.
  light_bg_offset: 0

1
2
3

{% note [class] [no-icon] [style] %}
Any content (supports inline tags too).
{% endnote %}

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

{% note simple %}
Default Callout Tag
{% endnote %}

{% note default simple %}
Default Callout Tag
{% endnote %}

{% note primary simple %}
Primary Callout Tag
{% endnote %}

{% note success simple %}
Success Callout Tag
{% endnote %}

{% note info simple %}
Info Callout Tag
{% endnote %}

{% note warning simple %}
Warning Callout Tag
{% endnote %}

{% note danger simple %}
Danger Callout Tag
{% endnote %}

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

{% note modern %}
Default Callout Tag
{% endnote %}

{% note default modern %}
Default Callout Tag
{% endnote %}

{% note primary modern %}
Primary Callout Tag
{% endnote %}

{% note success modern %}
Success Callout Tag
{% endnote %}

{% note info modern %}
Info Callout Tag
{% endnote %}

{% note warning modern %}
Warning Callout Tag
{% endnote %}

{% note danger modern %}
Danger Callout Tag
{% endnote %}

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

{% note flat %}
Default Callout Tag
{% endnote %}

{% note default flat %}
Default Callout Tag
{% endnote %}

{% note primary flat %}
Primary Callout Tag
{% endnote %}

{% note success flat %}
Success Callout Tag
{% endnote %}

{% note info flat %}
Info Callout Tag
{% endnote %}

{% note warning flat %}
Warning Callout Tag
{% endnote %}

{% note danger flat %}
Danger Callout Tag
{% endnote %}

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

{% note disabled %}
Default Callout Tag
{% endnote %}

{% note default disabled %}
Default Callout Tag
{% endnote %}

{% note primary disabled %}
Primary Callout Tag
{% endnote %}

{% note success disabled %}
Success Callout Tag
{% endnote %}

{% note info disabled %}
Info Callout Tag
{% endnote %}

{% note warning disabled %}
Warning Callout Tag
{% endnote %}

{% note danger disabled %}
Danger Callout Tag
{% endnote %}

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

{% note no-icon %}
Default Callout Tag
{% endnote %}

{% note default no-icon %}
Default Callout Tag
{% endnote %}

{% note primary no-icon %}
Primary Callout Tag
{% endnote %}

{% note success no-icon %}
Success Callout Tag
{% endnote %}

{% note info no-icon %}
Info Callout Tag
{% endnote %}

{% note warning no-icon %}
Warning Callout Tag
{% endnote %}

{% note danger no-icon %}
Danger Callout Tag
{% endnote %}

1
2
3

{% note [color] [icon] [style] %}
Any content (support inline tags too.io).
{% endnote %}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{% note 'fab fa-cc-visa' simple %}
Are you using Visa or UnionPay?
{% endnote %}
{% note blue 'fas fa-bullhorn' simple %}
2021 is coming soon...
{% endnote %}
{% note pink 'fas fa-car-crash' simple %}
Drive safely, safety first.
{% endnote %}
{% note red 'fas fa-fan' simple%}
Is this a three-blade fan or a four-blade fan?
{% endnote %}
{% note orange 'fas fa-battery-half' simple %}
Are you using Visa or UnionPay?
{% endnote %}
{% note purple 'far fa-hand-scissors' simple %}
Rock-paper-scissors.
{% endnote %}
{% note green 'fab fa-internet-explorer' simple %}
The most dreaded browser for front-end developers.
{% endnote %}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{% note 'fab fa-cc-visa' modern %}
Are you using Visa or UnionPay?
{% endnote %}
{% note blue 'fas fa-bullhorn' modern %}
2021 is coming soon...
{% endnote %}
{% note pink 'fas fa-car-crash' modern %}
Drive safely, safety first.
{% endnote %}
{% note red 'fas fa-fan' modern%}
Is this a three-blade fan or a four-blade fan?
{% endnote %}
{% note orange 'fas fa-battery-half' modern %}
Are you using Visa or UnionPay?
{% endnote %}
{% note purple 'far fa-hand-scissors' modern %}
Rock-paper-scissors.
{% endnote %}
{% note green 'fab fa-internet-explorer' modern %}
The most dreaded browser for front-end developers.
{% endnote %}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{% note 'fab fa-cc-visa' flat %}
Are you using Visa or UnionPay?
{% endnote %}
{% note blue 'fas fa-bullhorn' flat %}
2021 is coming soon...
{% endnote %}
{% note pink 'fas fa-car-crash' flat %}
Drive safely, safety first.
{% endnote %}
{% note red 'fas fa-fan' flat%}
Is this a three-blade fan or a four-blade fan?
{% endnote %}
{% note orange 'fas fa-battery-half' flat %}
Are you using Visa or UnionPay?
{% endnote %}
{% note purple 'far fa-hand-scissors' flat %}
Rock-paper-scissors.
{% endnote %}
{% note green 'fab fa-internet-explorer' flat %}
The most dreaded browser for front-end developers.
{% endnote %}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{% note 'fab fa-cc-visa' disabled %}
Are you using Visa or UnionPay?
{% endnote %}
{% note blue 'fas fa-bullhorn' disabled %}
2021 is coming soon...
{% endnote %}
{% note pink 'fas fa-car-crash' disabled %}
Drive safely, safety first.
{% endnote %}
{% note red 'fas fa-fan' disabled %}
Is this a three-blade fan or a four-blade fan?
{% endnote %}
{% note orange 'fas fa-battery-half' disabled %}
Are you using Visa or UnionPay?
{% endnote %}
{% note purple 'far fa-hand-scissors' disabled %}
Rock-paper-scissors.
{% endnote %}
{% note green 'fab fa-internet-explorer' disabled %}
The most dreaded browser for front-end developers.
{% endnote %}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{% note no-icon %}
Are you using Visa or UnionPay?
{% endnote %}
{% note blue no-icon %}
2021 is coming soon...
{% endnote %}
{% note pink no-icon %}
Drive safely, safety first.
{% endnote %}
{% note red no-icon %}
Is this a three-blade fan or a four-blade fan?
{% endnote %}
{% note orange no-icon %}
Are you using Visa or UnionPay?
{% endnote %}
{% note purple no-icon %}
Rock-paper-scissors.
{% endnote %}
{% note green no-icon %}
The most dreaded browser for front-end developers.
{% endnote %}

Gallery Photo Collection

Available from version 2.2.0

A collection of photo galleries.

Syntax:

1
2
3
4
5

<div class="gallery-group-main">
{% galleryGroup name description link img-url %}
{% galleryGroup name description link img-url %}
{% galleryGroup name description link img-url %}
</div>

• name: Name of the gallery
• description: Description of the gallery
• link: Link to the corresponding album
• img-url: URL of the gallery cover image

For example:

1
2
3
4
5

<div class="gallery-group-main">
{% galleryGroup 'Wallpapers' 'A collection of wallpapers' '/Gallery/wallpaper' https://i.loli.net/2019/11/10/T7Mu8Aod3egmC4Q.png %}
{% galleryGroup 'Marvel' 'Pictures related to Marvel' '/Gallery/marvel' https://i.loli.net/2019/12/25/8t97aVlp4hgyBGu.jpg %}
{% galleryGroup 'OH MY GIRL' 'Pictures related to OH MY GIRL' '/Gallery/ohmygirl' https://i.loli.net/2019/12/25/hOqbQ3BIwa6KWpo.jpg %}
</div>

Gallery Album

Available from version 2.0.0

The new Gallery Album is different from the old version. It automatically arranges images based on their length, making it more convenient to write, just like using markdown format. You can insert it into the corresponding markdown as needed.

1
2
3

{% gallery [lazyload],[rowHeight],[limit] %}
Markdown image format
{% endgallery %}

1
2
3
4
5
6
7
8
9
10
11

{% gallery %}
Markdown image format
{% endgallery %}

{% gallery true,220,10 %}
Markdown image format
{% endgallery %}

{% gallery true,,10 %}
Markdown image format
{% endgallery %}

1
2
3
4
5
6
7
8
9
10

{% gallery %}
![](https://i.loli.net/2019/12/25/Fze9jchtnyJXMHN.jpg)
![](https://i.loli.net/2019/12/25/ryLVePaqkYm4TEK.jpg)
![](https://i.loli.net/2019/12/25/gEy5Zc1Ai6VuO4N.jpg)
![](https://i.loli.net/2019/12/25/d6QHbytlSYO4FBG.jpg)
![](https://i.loli.net/2019/12/25/6nepIJ1xTgufatZ.jpg)
![](https://i.loli.net/2019/12/25/E7Jvr4eIPwUNmzq.jpg)
![](https://i.loli.net/2019/12/25/mh19anwBSWIkGlH.jpg)
![](https://i.loli.net/2019/12/25/2tu9JC8ewpBFagv.jpg)
{% endgallery %}

1
2

{% gallery url,[link],[lazyload],[rowHeight],[limit] %}
{% endgallery %}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

[
  {
    "url": "https://cdn.jsdelivr.net/gh/jerryc127/CDN/img/IMG_0556.jpg",
    "alt": "IMG_0556.jpg",
     "title": "This is title"
  },
  {
    "url": "https://cdn.jsdelivr.net/gh/jerryc127/CDN/img/IMG_0472.jpg",
    "alt": "IMG_0472.jpg"
  },
  {
    "url": "https://cdn.jsdelivr.net/gh/jerryc127/CDN/img/IMG_0453.jpg",
    "alt": ""
  },
  {
    "url": "https://cdn.jsdelivr.net/gh/jerryc127/CDN/img/IMG_0931.jpg",
    "alt": ""
  }
]

1
2
3
4
5
6
7
8

{% gallery url,https://xxxx.com/sss.json %}
{% endgallery %}

{% gallery url,https://xxxx.com/sss.json,true,220,10 %}
{% endgallery %}

{% gallery url,https://xxxx.com/sss.json,true,,10 %}
{% endgallery %}

tag-hide

If you want to hide certain text or content and provide a button for users to click and reveal it, you can use this tag-hide plugin.

1

{% hideInline content,display,bg,color %}

1
2
3

Which English letter is the coolest? {% hideInline Because they wear suits (C for cool),Reveal the answer,#FF7242,#fff %}

There's a person standing inside the door? {% hideInline Blink %}

1
2
3

{% hideBlock display,bg,color %}
content
{% endhideBlock %}

1
2
3
4

Reveal the answer
{% hideBlock Reveal the answer %}
Fool, there is no answer!
{% endhideBlock %}

1
2
3

{% hideToggle display,bg,color %}
content
{% endhideToggle %}

1
2
3
4
5
6
7
8
9
10

{% hideToggle Butterfly Installation Method %}
In your blog's root directory,

git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/Butterfly

If you want to install the newer dev branch, you can use

git clone -b dev https://github.com/jerryc127/hexo-theme-butterfly.git themes/Butterfly

{% endhideToggle %}

Mermaid

The mermaid tag allows you to create various diagrams like Flowchart, Sequence diagram, Class Diagram, State Diagram, Gantt chart, and Pie Chart. Here's how you can use it:

1. Modify your theme configuration file (usually in YAML format) to enable mermaid:

1
2
3
4
5
6
7
8

# mermaid
# see https://github.com/mermaid-js/mermaid
mermaid:
  enable: true
  # built-in themes: default/forest/dark/neutral
  theme:
    light: default
    dark: dark

2. To create a diagram, use the mermaid tag plugin with your content inside:

1
2
3

{% mermaid %}
Your content here
{% endmermaid %}

Example:

1
2
3
4
5
6
7
8

{% mermaid %}
pie
    title Key elements in Product X
    "Calcium" : 42.96
    "Potassium" : 50.05
    "Magnesium" : 10.01
    "Iron" :  5
{% endmermaid %}

This will generate a Pie Chart diagram:

You can refer to the mermaid documentation for more information and examples on how to create different types of diagrams using mermaid.

Tabs

Usage:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{% tabs Unique name, [index] %}
<!-- tab [Tab caption] [@icon] -->
Any content (support inline tags too).
<!-- endtab -->
{% endtabs %}

Unique name   : Unique name of tabs block tag without comma.
                Will be used in #id's as prefix for each tab with their index numbers.
                If there are whitespaces in name, for generate #id all whitespaces will replaced by dashes.
                Only for current url of post/page must be unique!
[index]       : Index number of active tab.
                If not specified, first tab (1) will be selected.
                If index is -1, no tab will be selected. It's will be something like spoiler.
                Optional parameter.
[Tab caption] : Caption of current tab.
                If not caption specified, unique name with tab index suffix will be used as caption of tab.
                If not caption specified, but specified icon, caption will empty.
                Optional parameter.
[@icon]       : FontAwesome icon name (full-name, look like 'fas fa-font')
                Can be specified with or without space; e.g. 'Tab caption @icon' similar to 'Tab caption@icon'.
                Optional parameter.

Demo 1 - Default selection of the first tab (Default):

1
2
3
4
5
6
7
8
9
10
11
12
13

{% tabs test1 %}
<!-- tab -->
**This is Tab 1.**
<!-- endtab -->

<!-- tab -->
**This is Tab 2.**
<!-- endtab -->

<!-- tab -->
**This is Tab 3.**
<!-- endtab -->
{% endtabs %}

Demo 2 - Specify the default selected tab

1
2
3
4
5
6
7
8
9
10
11
12
13

{% tabs test2, 3 %}
<!-- tab -->
**This is Tab 1.**
<!-- endtab -->

<!-- tab -->
**This is Tab 2.**
<!-- endtab -->

<!-- tab -->
**This is Tab 3.**
<!-- endtab -->
{% endtabs %}

Demo 3 - No default selected tab

1
2
3
4
5
6
7
8
9
10
11
12
13

{% tabs test3, -1 %}
<!-- tab -->
**This is Tab 1.**
<!-- endtab -->

<!-- tab -->
**This is Tab 2.**
<!-- endtab -->

<!-- tab -->
**This is Tab 3.**
<!-- endtab -->
{% endtabs %}

Demo 4 - Custom tab names + Only icon + Icon and Tab name:

1
2
3
4
5
6
7
8
9
10
11
12
13

{% tabs test4 %}
<!-- tab First Tab -->
**The name of this tab is "First Tab".**
<!-- endtab -->

<!-- tab @fab fa-apple-pay -->
**Only icon, no tab name.**
<!-- endtab -->

<!-- tab Bomb @fas fa-bomb -->
**Tab name + icon**
<!-- endtab -->
{% endtabs %}

Button

Version 3.0 and above

Usage:

1

{% btn [url],[text],[icon],[color] [style] [layout] [position] [size] %}

Parameters:

• [url]: Link to the destination.
• [text]: Button text.
• [icon]: [Optional] Icon for the button.
• [color]: [Optional] Background color of the button (for default style),
  font and border color (for outline style).
  Available colors: default, blue, pink, red, purple, orange, green.
• [style]: [Optional] Button style. Default is solid.
  Options: outline or leave empty for solid style.
• [layout]: [Optional] Button layout. Default is line.
  Options: block or leave empty for line layout.
• [position]: [Optional] Button position. Applicable only when the layout is set to block.
  Default is left.
  Options: center, right, or leave empty for left position.
• [size]: [Optional] Button size.
  Options: larger or leave empty.

Demo

1
2
3
4
5

This is my website, click the button {% btn 'https://butterfly.js.org/',Butterfly %}
This is my website, click the button {% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right %}
This is my website, click the button {% btn 'https://butterfly.js.org/',Butterfly,,outline %}
This is my website, click the button {% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline %}
This is my website, click the button {% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,larger %}

This is my website, click the button Butterfly
This is my website, click the button Butterfly
This is my website, click the button Butterfly
This is my website, click the button Butterfly
This is my website, click the button Butterfly

1
2
3

{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,block %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,block center larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,block right outline larger %}

more than one button in center

1
2
3
4
5
6
7

{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,blue larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,pink larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,red larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,purple larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,orange larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,green larger %}

1
2
3
4
5
6
7
8
9

<div class="btn-center">
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline blue larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline pink larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline red larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline purple larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline orange larger %}
{% btn 'https://butterfly.js.org/',Butterfly,far fa-hand-point-right,outline green larger %}
</div>

inlineImg

The theme displays images as default block-level elements. If you want to display an image as an inline element, you can use this tag plugin.

1
2
3
4

{% inlineImg [src] [height] %}

[src]      :    Image link
[height]   :    Image height limit [Optional]

Demo

1
2
3
4
5

Do you think I look beautiful?

![](https://i.loli.net/2021/03/19/2P6ivUGsdaEXSFI.png)

I think I look beautiful {% inlineImg https://i.loli.net/2021/03/19/5M4jUB3ynq7ePgw.png 150px %}

label

Highlight the required text.

1

{% label text color %}

Demo

1
2

臣亮言：{% label 先帝 %}創業未半，而{% label 中道崩殂 blue %}。今天下三分，{% label 益州疲敝 pink %}，此誠{% label 危急存亡之秋 red %}也！然侍衞之臣，不懈於內；{% label 忠志之士 purple %}，忘身於外者，蓋追先帝之殊遇，欲報之於陛下也。誠宜開張聖聽，以光先帝遺德，恢弘志士之氣；不宜妄自菲薄，引喻失義，以塞忠諫之路也。
宮中、府中，俱為一體；陟罰臧否，不宜異同。若有{% label 作奸 orange %}、{% label 犯科 green %}，及為忠善者，宜付有司，論其刑賞，以昭陛下平明之治；不宜偏私，使內外異法也。

臣亮言：先帝 創業未半，而中道崩殂 。今天下三分，益州疲敝 ，此誠危急存亡之秋 也！然侍衞之臣，不懈於內；忠志之士 ，忘身於外者，蓋追先帝之殊遇，欲報之於陛下也。誠宜開張聖聽，以光先帝遺德，恢弘志士之氣；不宜妄自菲薄，引喻失義，以塞忠諫之路也。

宮中、府中，俱為一體；陟罰臧否，不宜異同。若有作奸 、犯科 ，及為忠善者，宜付有司，論其刑賞，以昭陛下平明之治；不宜偏私，使內外異法也。

timeline

Supported in version 4.0.0 and above

1
2
3
4
5
6
7
8

{% timeline title,color %}
<!-- timeline title -->
xxxxx
<!-- endtimeline -->
<!-- timeline title -->
xxxxx
<!-- endtimeline -->
{% endtimeline %}

Demo

1
2
3
4
5

{% timeline 2022 %}
<!-- timeline 01-02 -->
This is a test page.
<!-- endtimeline -->
{% endtimeline %}

1
2
3
4
5

{% timeline 2022,blue %}
<!-- timeline 01-02 -->
This is a test page.
<!-- endtimeline -->
{% endtimeline %}

1
2
3
4
5

{% timeline 2022,pink %}
<!-- timeline 01-02 -->
This is a test page.
<!-- endtimeline -->
{% endtimeline %}

1
2
3
4
5

{% timeline 2022,red %}
<!-- timeline 01-02 -->
This is a test page.
<!-- endtimeline -->
{% endtimeline %}

1
2
3
4
5

{% timeline 2022,purple %}
<!-- timeline 01-02 -->
This is a test page.
<!-- endtimeline -->
{% endtimeline %}

1
2
3
4
5

{% timeline 2022,orange %}
<!-- timeline 01-02 -->
This is a test page.
<!-- endtimeline -->
{% endtimeline %}

1
2
3
4
5

{% timeline 2022,green %}
<!-- timeline 01-02 -->
This is a test page.
<!-- endtimeline -->
{% endtimeline %}

flink

Supported in version 4.1.0

You can insert a friends link list effect on any page.

The content format is the same as the friends link page and supports YAML format.

1
2
3

{% flink %}
xxxxxx
{% endflink %}

Demo

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

{% flink %}
- class_name: Friendly Links
  class_desc: Those people, those things
  link_list:
    - name: Hexo
      link: https://hexo.io/zh-tw/
      avatar: https://d33wubrfki0l68.cloudfront.net/6657ba50e702d84afb32fe846bed54fba1a77add/827ae/logo.svg
      descr: Fast, simple, and powerful blog framework.

- class_name: Websites
  class_desc: Recommended websites
  link_list:
    - name: Youtube
      link: https://www.youtube.com/
      avatar: https://i.loli.net/2020/05/14/9ZkGg8v3azHJfM1.png
      descr: Video website
    - name: Weibo
      link: https://www.weibo.com/
      avatar: https://i.loli.net/2020/05/14/TLJBum386vcnI1P.png
      descr: China's largest social sharing platform
    - name: Twitter
      link: https://twitter.com/
      avatar: https://i.loli.net/2020/05/14/5VyHPQqR6LWF39a.png
      descr: Social sharing platform
{% endflink %}

abcjs Sheet Music

Rendering sheet music on the page.

Modify the theme configuration file.

1
2
3
4
5
6

# abcjs (Sheet Music Rendering)
# See https://github.com/paulrosen/abcjs
# ---------------
abcjs:
  enable: true
  per_page: true

Usage:

1
2
3

{% score %}
Sheet music code
{% endscore %}

Demo

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{% score %}
X:1
T:alternate heads
M:C
L:1/8
U:n=!style=normal!
K:C treble style=rhythm
"Am" BBBB B2 B>B | "Dm" B2 B/B/B "C" B4 |"Am" B2 nGnB B2 nGnA | "Dm" nDB/B/ nDB/B/ "C" nCB/B/ nCB/B/ |B8| B0 B0 B0 B0 |]
%%text This translates to:
[M:C][K:style=normal]
[A,EAce][A,EAce][A,EAce][A,EAce] [A,EAce]2 [A,EAce]>[A,EAce] |[DAdf]2 [DAdf]/[DAdf]/[DAdf] [CEGce]4 |[A,EAce]2 GA [A,EAce] GA |D[DAdf]/[DAdf]/ D[DAdf]/[DAdf]/ C [CEGce]/[CEGce]/ C[CEGce]/[CEGce]/ |[CEGce]8 | [CEGce]2 [CEGce]2 [CEGce]2 [CEGce]2 |]
GAB2 !style=harmonic![gb]4|GAB2 [K: style=harmonic]gbgb|
[K: style=x]
C/A,/ C/C/E C/zz2|
w:Rock-y did-nt like that
{% endscore %}

series articles

Display series articles on the page.

Modify the theme configuration file.

1
2
3
4
5

series:
   enable: true
   orderBy: 'title' # Order by title or date
   order: 1 # Sort of order. 1, asc for ascending; -1, desc for descending
   number: true

Usage:

1
2

{% series %}
{% series [series name] %}

Add the parameter series to the front matter of the article and give it an identifier.

Using this tag plugin will display articles with the same identifier in a list format.

If the series identifier is not specified, it defaults to the series identifier of the article where this tag plugin is used.

Demo

1

{% series markdown %}