📖 本教程更新於 2021 年 05 月 11 日，教程的內容針對最新穩定版而更新（如果你是舊版，教程會有些出入，請留意）

🦋 Butterfly 已經更新到 3.7.7

📚 文檔目錄

🚀 快速開始 - 📑 主題頁面 - 🛠 主題配置-1 - ⚔️ 主題配置-2 - ❓ 主題問答 - ⚡️ 進階教程 - ✨ 更新日誌 - 🤞 打賞

你可以通過右下角的 簡 按鈕切換為簡體顯示

評論

從3.0.0開始，開啟評論需要在comments-use中填寫你需要的評論。

支持雙評論顯示，只需要配置兩個評論（第一個為默認顯示）

1
2
3
4
5
6
7
8
9
10
11
comments:
  # Up to two comments system, the first will be shown as default
  # Choose: Disqus/Disqusjs/Livere/Gitalk/Valine/Waline/Utterances/Facebook Comments/Twikoo
  use:
    - Valine
  text: true # Display the comment name next to the button
  # lazyload: The comment system will be load when comment element enters the browser's viewport.
  # If you set it to true, the comment count will be invalid
  lazyload: true
  count: true # Display comment count in top_img
  card_post_count: false # Display comment count in Home Page
參數 解釋
use 使用的評論（請注意，填寫的評論首字母需要大寫。最多支持兩個，如果不需要請留空）
注意：雙評論不能是 Disqus 和 Disqusjs 一起，由於其共用同一個 ID，會出錯
text 是否顯示評論服務商的名字
lazyload 是否為評論開啟lazyload，開啟後，只有滾動到評論位置時才會加載評論所需要的資源（開啟lazyload後，評論數將不顯示）
count 是否在文章頂部顯示評論數
livere 和 utterances 不支持評論數顯示
card_post_count 是否在首頁文章卡片顯示評論數
gitalk、livere 和 utterances 不支持評論數顯示

單評論

image-20200731172506907

雙評論

image-20200731173006128

顯示text

image-20200731173006128

不顯示text

image-20200731173143712

註冊 disqus，配置你自己的 disqus，然後在Butterfly裏開啟它。

修改 主題配置文件

1
2
disqus:
  shortname:

image-20201027211418161

與Disqus一樣，但由於Disqus在中國大陸無法訪問， 使用Disqusjs可以在無法訪問Disqus時顯示評論。具體可參考Disqusjs。

修改 主題配置文件

1
2
3
4
5
6
7
8
disqusjs:
  shortname:
  siteName:
  apikey:
  api:
  nocomment: # display when a blog post or an article has no comment attached
  admin:
  adminLabel:

當無法訪問 Disqus 時，會顯示

image-20201027212543851

註冊來必力，配置你自己的來必力設置，然後在Butterfly裏開啟它。

修改 主題配置文件

1
2
livere:
  uid:

laibili 的 uid 你能在這裏找到:

遵循 gitalk的指示去獲取你的 github Oauth 應用的 client id 和 secret 值。以及查看它的相關配置説明。

然後修改 主題配置文件:

1
2
3
4
5
6
7
8
9
10
11
12
gitalk:
  client_id: 你的client id 
  client_secret: 你的client secret
  repo: 你的github倉庫
  owner: 你的github用户名
  admin: 該倉庫的擁有者或協作者
  language: zh-CN # en, zh-CN, zh-TW, es-ES, fr, ru
  perPage: 10 # Pagination size, with maximum 100.
  distractionFreeMode: false # Facebook-like distraction free mode.
  pagerDirection: last # Comment sorting direction, available values are last and first.
  createIssueManually: false # Gitalk will create a corresponding github issue for your every single page automatically
  option:

image-20201027212704930

遵循 Valine的指示去配置你的 LeanCloud 應用。以及查看相應的配置説明。

然後修改 主題配置文件:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
valine:
  appId:  # leancloud application app id
  appKey:  # leancloud application app key
  pageSize: 10 # comment list page size
  avatar: monsterid # gravatar style https://valine.js.org/#/avatar
  lang: en # i18n: zh-CN/zh-TW/en/ja
  placeholder: 記得留下你的暱稱和郵箱....可以快速收到回復 # valine comment input placeholder(like: Please leave your footprints )
  guest_info: nick,mail,link #valine comment header info (nick/mail/link)
  recordIP: false # Record reviewer IP
  serverURLs: # This configuration is suitable for domestic custom domain name users, overseas version will be automatically detected (no need to manually fill in)
  bg: /img/comment_bg.png # valine background
  emojiCDN: # emoji CDN
  enableQQ: false # enable the Nickname box to automatically get QQ Nickname and QQ Avatar
  requiredFields: nick,mail # required fields (nick/mail)
  visitor: false
  option:

Valine於 v1.4.5 開始支持自定義表情，如果你需要自行配置，請在emojiCDN配置表情CDN。

同時在Hexo 工作目錄下的source/_data/創建一個json文件valine.json,等同於Valine需要配置的emojiMaps，valine.json配置方式可參考如下

valine.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{ 
"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"
}

default_avatar

參數 效果
留空（默認）
mp
identicon
monsterid
wavatar
retro
robohash
blank
404

Waline - 一款從 Valine 衍生的帶後端評論系統。可以將 Waline 等價成 With backend Valine。

具體配置可參考 waline 文檔

然後修改 主題配置文件:

1
2
3
4
5
6
7
8
9
# waline - A simple comment system with backend support fork from Valine
# https://waline.js.org/
waline:
  serverURL:  # Waline server address url
  avatar: monsterid # gravatar style https://zh-tw.gravatar.com/site/implement/images/#default-image
  bg: /img/comment_bg.png # waline background
  emojiCDN: # emoji CDN
  visitor: false
  option:

如果你需要自定義表情，請在emojiCDN配置表情CDN。

同時在Hexo 工作目錄下的source/_data/創建一個json文件waline.json,等同於Waline需要配置的emojiMaps，waline.json配置方式可參考如下

waline.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{ 
"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"
}

與Gitalk一樣，基於 GitHub issues 的評論工具。相對於Gitalk,其相對需要權限較少。具體配置可參考Utterances。

修改 主題配置文件:

1
2
3
4
5
6
7
utterances:
  repo:
  # 可選 pathname/url/title/og:title
  issue_term: pathname
  # 可選 github-light/github-dark/github-dark-orange/icy-dark/dark-blue/photon-dark
  light_theme: github-light
  dark_theme: photon-dark

Facebook Comments是Facebook提供的評論插件，需要登陸Facebook才可評論。

修改 主題配置文件

1
2
3
4
5
6
7
8
# Facebook Comments Plugin
# https://developers.facebook.com/docs/plugins/comments/
facebook_comments:
  app_id: 
  user_id: # optional
  pageSize: 10 # The number of comments to show
  order_by: social # social/time/reverse_time
  lang: en_US # Language en_US/zh_CN/zh_TW and so on

Twikoo 是一個簡潔、安全、無後端的靜態網站評論系統，基於騰訊雲開發。

具體如何配置評論，請查看 Twikoo文檔

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

修改 主題配置文件

1
2
3
4
5
twikoo:
  envId:
  region:
  visitor: false
  option:
參數 解釋
envId 環境 ID
region 環境地域，默認為 ap-shanghai，如果您的環境地域不是上海，需傳此參數
visitor 是否顯示文章閲讀數
option 可選配置

在綫聊天

從3.0開始，Butterfly主題內置了多種在綫聊天工具。你可以選擇開啟一種，方便你與訪客的交流。

這些工具都提供了一個按鈕可以打開/關閉聊天窗口。
主題也提供了一個集合主題特色的按鈕來替換這些工具本身的按鈕，這個聊天按鈕將會出現在右下角裏。
你只需要把chat_btn打開就行。

修改 主題配置文件

1
2
3
# Chat Button [recommend]
# It will create a button in the bottom right corner of website, and hide the origin button
chat_btn: true

為了不影響訪客的體驗，主題提供一個chat_hide_show配置
設為true後，使用工具提供的按鈕時，只有向上滾動才會顯示聊天按鈕，向下滾動時會隱藏按鈕。

修改 主題配置文件

1
2
# The origin chat button is displayed when scrolling up, and the button is hidden when scrolling down
chat_hide_show: true

如果使用工具自帶的聊天按鈕，按鈕位置可能會遮擋右下角圖標，請配置rightside-bottom調正右下角圖標位置

配置chatra,需要知道Public key

打開chatra並註冊賬號。
你可以在Preferences中找到Public key

修改 主題配置文件

1
2
3
4
5
# chatra
# https://chatra.io/
chatra:
  enable: true
  id: xxxxxxxx

chatra的樣式你可以Chat Widget自行配置

Demo

配置tidio,需要知道Public key

打開tidio並註冊賬號。
你可以在Preferences > Developer中找到Public key

修改 主題配置文件

1
2
3
4
5
# tidio
# https://www.tidio.com/
tidio:
  enable: true
  public_key: XXXX

tidio的樣式你可以Channels自行配置

Demo

打開daovoice和註冊帳號
找到你的app id

修改 主題配置文件

1
2
3
4
5
# daovoice
# http://daovoice.io/
daovoice:
  enable: true
  app_id: xxxxx

可在聊天設置裏配置聊天按鈕等樣式

Demo

打開Gitter和註冊賬號
創建一個community或者room,複製名稱到設置去

修改 主題配置文件

1
2
3
4
5
# gitter
# https://gitter.im/
gitter:
  enable: true
  room:

Demo

打開crisp並註冊帳號

找到需要的網站ID

1
2
3
4
5
# crisp
# https://crisp.chat/en/
crisp:
  enable: false
  website_id: xxxxxxxx

image-20200731183023863

image-20200731183444781

分享

只能選擇一個分享服務商

訪問 AddThis 官網
找到你的 pub-id

修改 主題配置文件

1
2
3
addThis:
  enable: true # or false
  pubid: 你的pub-id

如果你不知道 sharejs，看看它的説明。

修改 主題配置文件

1
2
3
sharejs:
  enable: true
  sites: facebook,twitter,wechat,weibo,qq  #想要顯示的內容

可以到addtoany查看使用説明

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

搜索系統

網站驗證

如果需要搜索引擎收錄網站，可能需要登錄對應搜索引擎的管理平台進行提交。
各自的驗證碼可從各自管理平台拿到

修改 主題配置文件

1
2
3
4
5
site_verification:
  # - name: google_site_verification
  #   content: xxxxxx
  # - name: baidu_site_verification
  #   content: xxxxxxx

分析統計

  1. 登錄百度統計的官方網站

  2. 找到你百度統計的統計代碼

  1. 修改 主題配置文件
1
baidu_analytics: 你的代碼

  1. 登錄谷歌分析的官方網站

  2. 找到你的谷歌分析的跟蹤 ID

  1. 修改 主題配置文件
1
google_analytics: 你的代碼 # 通常以`UA-`打頭

由於騰訊分析將於20年12月關閉並遷移到騰訊移動分析,從 3.1.0 起，騰訊分析改為騰訊移動分析。

  1. 登錄騰訊移動分析的官方網站
  2. 選擇 WEB應用
  3. 找到你的站點ID

  1. 修改 主題配置文件
1
2
# Tencent_analytics ID
tencent_analytics:
  1. 登錄CNZZ分析的官方網站
  2. 找到 站點設置 - 獲取代碼
  3. 找到你的 web_id

  1. 修改 主題配置文件
1
cnzz_analytics:
  1. 登錄 Cloudflare 分析的官方網站
  2. 找到 JavaScript 程式碼片段
  3. 找到你的 token

image-20201230195158742

  1. 修改 主題配置文件

    1
    2
    3
    # Cloudflare Analytics
    # https://www.cloudflare.com/zh-tw/web-analytics/
    cloudflare_analytics:

  1. 登錄 Clarity 的官方網站

  2. 創建 PROJECT

  3. 找到你的 IDimage-20201230195541443

  4. 修改 主題配置文件

    1
    2
    3
    # Microsoft Clarity
    # https://clarity.microsoft.com/
    microsoft_clarity:

廣告

主題已集成谷歌廣告（自動廣告）

修改 主題配置文件

1
2
3
4
5
6
google_adsense:
  enable: true
  auto_ads: true
  js: https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js
  client: # 填入個人識別碼
  enable_page_level_ads: true

主題預留了三個位置可供插入廣告，分別為主頁文章(每三篇文章出現廣告)/aside公告之後/文章頁打賞之後。
把html代碼填寫到對應的位置

修改 主題配置文件

1
2
3
4
ad:
  index:
  aside:
  post:

例如:

1
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>


Math 數學

建議使用 KaTex 獲得更好的效果，下文有介紹！

修改 主題配置文件:

1
2
3
4
5
mathjax:
  enable: true
  # true 表示每一頁都加載mathjax.js
  # false 需要時加載，須在使用的Markdown Front-matter 加上 mathjax: true
  per_page: false

如果per_page設為true,則每一頁都會加載Mathjax服務。設為false，則需要在文章Front-matter添加mathjax: true,對應的文章才會加載Mathjax服務。

然後你需要修改一下默認的markdown渲染引擎來實現 MathJax 的效果。

查看: hexo-renderer-kramed

以下操作在你 hexo 博客的目錄下 (不是 Butterfly 的目錄!):

效果：

首先禁用MathJax（如果你配置過 MathJax 的話），然後修改你的主題配置文件以便加載katex.min.css:

1
2
3
4
5
6
katex:
  enable: true
  # true 表示每一頁都加載katex.js
  # false 需要時加載，須在使用的Markdown Front-matter 加上 katex: true
  per_page: false
  hide_scrollbar: true

你不需要添加katex.min.js來渲染數學方程。相應的你需要卸載你之前的 hexo 的 markdown 渲染器，然後安裝其它插件。

卸載掉 marked 插件，安裝 hexo-renderer-markdown-it

1
2
3
4
5
npm un hexo-renderer-marked --save # 如果有安裝這個的話，卸載
npm un hexo-renderer-kramed --save # 如果有安裝這個的話，卸載

npm i hexo-renderer-markdown-it --save # 需要安裝這個渲染插件
npm install @neilsustc/markdown-it-katex --save #需要安裝這個katex插件

在 hexo 的根目錄的 _config.yml 中配置

1
2
3
4
5
6
markdown:
  plugins:
    - plugin:
      name: '@neilsustc/markdown-it-katex'
      options:
        strict: false

如需配置其它參數，請參考 katex 官網

注意，此方法生成的 katex 沒有斜體

卸載掉 marked 插件，然後安裝新的hexo-renderer-markdown-it-plus:

1
2
3
4
5
6
7
8
9
10
11
# 替換 `hexo-renderer-kramed` 或者 `hexo-renderer-marked` 等hexo的markdown渲染器
# 你可以在你的package.json裏找到hexo的markdwon渲染器，並將其卸載
npm un hexo-renderer-marked --save

# or

npm un hexo-renderer-kramed --save


# 然後安裝 `hexo-renderer-markdown-it-plus`
npm i @upupming/hexo-renderer-markdown-it-plus --save

注意到 hexo-renderer-markdown-it-plus已經無人持續維護, 所以我們使用 @upupming/hexo-renderer-markdown-it-plus。 這份 fork 的代碼使用了 @neilsustc/markdown-it-katex同時它也是 VSCode 的插件 Markdown All in One所使用的, 所以我們可以獲得最新的 KaTex 功能例如 \tag{}。

你還可以通過 @neilsustc/markdown-it-katex控制 KaTeX 的設置，所有可配置的選項參見 https://katex.org/docs/options.html。 比如你想要禁用掉 KaTeX 在命令行上輸出的宂長的警告信息，你可以在根目錄的 _config.yml 中使用下面的配置將 strict 設置為 false:

1
2
3
4
5
6
7
markdown_it_plus:
  plugins:
    - plugin:
      name: '@neilsustc/markdown-it-katex'
      enable: true
      options:
        strict: false

當然，你還可以利用這個特性來定義一些自己常用的 macros。

因為 KaTeX 更快更輕量，因此沒有 MathJax 的功能多（比如右鍵菜單）。為那些使用 MathJax 的用户，主題也內置了 katex 的 複製 功能。

美化/特效

自定義主題色

可以修改大部分UI顏色

修改 主題配置文件，比如：

顏色值必須被雙引號包裹，就像"#000"而不是#000。否則將會在構建的時候報錯！

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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"


網站背景

默認顯示白色，可設置圖片或者顏色

修改 主題配置文件

1
2
3
4
# 圖片格式 url(http://xxxxxx.com/xxx.jpg)
# 顏色（HEX值/RGB值/顔色單詞/漸變色)
# 留空 不顯示背景
background:

留意: 如果你的網站根目錄不是’/',使用本地圖片時，需加上你的根目錄。
例如：網站是 https://yoursite.com/blog,引用一張img/xx.png圖片，則設置background為 `url(/blog/img/xx.png)

background:‘#49B202’

background: url(https://i.loli.net/2019/09/09/5oDRkWVKctx2b6A.png)

修改 主題配置文件

1
2
# footer是否顯示圖片背景(與top_img一致)
footer_bg: true
配置的值 效果
留空/false 顯示默認的顔色
img鏈接 圖片的鏈接，顯示所配置的圖片
顔色(
HEX值 - #0000FF
RGB值 - rgb(0,0,255)
顔色單詞 - orange
漸變色 - linear-gradient( 135deg, #E2B0FF 10%, #9F44D3 100%)
）		 對應的顔色
true 顯示跟 top_img 一樣

true

打字效果

打字效果activate-power-mode

修改 主題配置文件

1
2
3
4
5
6
7
# Typewriter Effect (打字效果)
# https://github.com/disjukr/activate-power-mode
activate_power_mode:
  enable: true
  colorful: true # open particle animation (冒光特效)
  shake: true #  open shake (抖動特效)
  mobile: false

背景特效

好看的綵帶背景，可設置每次刷新更換綵帶，或者每次點擊更換綵帶
修改 主題配置文件

1
2
3
4
5
6
7
canvas_ribbon:
  enable: false
  size: 150
  alpha: 0.6
  zIndex: -1
  click_to_change: false  #設置是否每次點擊都更換綵帶
  mobile: false # false 手機端不顯示 true 手機端顯示

相關配置可查看canvas_ribbon

好看的綵帶背景，會飄動
修改 主題配置文件

1
2
3
canvas_fluttering_ribbon:
  enable: true
  mobile: false # false 手機端不顯示 true 手機端顯示

修改 主題配置文件

1
2
3
4
5
6
7
canvas_nest:
  enable: true
  color: '0,0,255' #color of lines, default: '0,0,0'; RGB values: (R,G,B).(note: use ',' to separate.)
  opacity: 0.7 # the opacity of line (0~1), default: 0.5.
  zIndex: -1 # z-index property of the background, default: -1.
  count: 99 # the number of lines, default: 99.
  mobile: false # false 手機端不顯示 true 手機端顯示

鼠標點擊效果

zIndex建議只在-1和9999上選
-1 代表煙火效果在底部
9999 代表煙火效果在前面

修改 主題配置文件

1
2
3
4
fireworks:
  enable: true
  zIndex: 9999 # -1 or 9999
  mobile: false

修改 主題配置文件

1
2
3
4
# 點擊出現愛心
click_heart:
  enable: true
  mobile: false

修改 主題配置文件

1
2
3
4
5
6
7
8
9
10
# 點擊出現文字，文字可自行修改
ClickShowText:
  enable: false
  text:
    - I
    - LOVE
    - YOU
  fontSize: 15px
  random: false # 文字隨機顯示
  mobile: false

頁面美化

會改變ol、ul、h1-h5的樣式

field配置生效的區域

  • post 只在文章頁生效
  • site 在全站生效

修改 主題配置文件

1
2
3
4
5
6
# 美化頁面顯示
beautify:
  enable: true
  field: site # site/post
  title-prefix-icon: '\f0c1'
  title-prefix-icon-color: "#F47466"

title-prefix-icon填寫的是fontawesome的icon的Unicode數。

未開啟美化

開啟美化

自定義字體和字體大小

全局字體

可自行設置字體的font-family
如不需要配置，請留空

修改 主題配置文件

1
2
3
4
5
6
7
# Global font settings
# Don't modify the following settings unless you know how they work (非必要不要修改)
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

Blog 標題字體

可自行設置字體的font-family
如不需要配置，請留空。
如不需要使用網絡字體，只需要把font_link留空就行

修改 主題配置文件

1
2
3
4
5
# Font settings for the site title and site subtitle
# 左上角網站名字 主頁居中網站名字
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

網站副標題

可設置主頁中顯示的網站副標題或者喜歡的座右銘。

修改 主題配置文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 主頁subtitle
subtitle:
  enable: true
  # 打字效果
  effect: true
  # 循環或者只打字一次
  loop: false
  # source調用第三方服務
  # source: false 關閉調用
  # source: 1  調用搏天api的隨機語錄（簡體） 
  # source: 2  調用一言網的一句話（簡體） 
  # source: 3  調用一句網（簡體） 
  # source: 4  調用今日詩詞（簡體
  # subtitle 會先顯示 source , 再顯示 sub 的內容
  source: false
  # 如果有英文逗號' , ',請使用轉義字元 &#44;
  # 如果有英文雙引號' " ',請使用轉義字元 &quot;
  # 開頭不允許轉義字元，如需要，請把整個句子用雙引號包住
  # 例如 ”&quotNever put off till tomorrow what you can do today&quot"
  # 如果關閉打字效果，subtitle只會顯示sub的第一行文字
  sub:
    - 今日事&#44;今日畢
    - Never put off till tomorrow what you can do today

主頁top_img顯示大小

適用於 版本號 >= V1.2.0

默認的顯示為全屏。site-info的區域會居中顯示

1
2
3
4
5
# 主頁設置
# 默認top_img全屏，site_info在中間
# 使用默認, 都無需填寫（建議默認）
index_site_info_top: # 主頁標題距離頂部距離  例如 300px/300em/300rem/10%
index_top_img_height:  #主頁top_img高度 例如 300px/300em/300rem  不能使用百分比

注意：index_top_img_height的值不能使用百分比。
2個都不填的話，會使用默認值

舉例，當

1
index_top_img_height: 400px

效果

頁面加載動畫preloader

當進入網頁時，因為加載速度的問題，可能會導致top_img圖片出現斷層顯示，或者網頁加載不全而出現等待時間，開啟preloader後，會顯示加載動畫，等頁面加載完，加載動畫會消失。

配置butterly.yml

1
2
# 加載動畫 Loading Animation
preloader: true

PWA

要為Butterfly配上 PWA 特性, 你需要如下幾個步驟:

  1. 打開 hexo 工作目錄

  2. npm install hexo-offline --save 或者 yarn add hexo-offline

  3. 修改_config.yml 在站點_config.yml中增加以下內容。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# offline config passed to sw-precache.
offline:
  maximumFileSizeToCacheInBytes: 10485760 # 緩存的最大文件大小，以字節為單位
  staticFileGlobs:
    - public/**/*.{js,html,css,png,jpg,gif,svg,webp,eot,ttf,woff,woff2}
  # 靜態文件合集，如果你的站點使用了例如webp格式的文件，請將文件類型添加進去。
  stripPrefix: public
  verbose: true
  runtimeCaching:
    # CDNs - should be cacheFirst, since they should be used specific versions so should not change
    - urlPattern: /* # 如果你需要加載CDN資源，請配置該選項，如果沒有，可以不配置。
      handler: cacheFirst
      options:
        origin: your_websie_url # 可替換成你的 url

更多內容請查看 hexo-offline的官方文檔

  1. 在主題配置文件中開啟 pwa 選項。
1
2
3
4
5
6
7
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
  1. 在創建source/目錄中創建manifest.json文件。
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
{
    "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
  }

你也可以通過 Web App Manifest快速創建manifest.json。（Web App Manifest 要求至少包含一個 512*512 像素的圖標）

  1. 可以通過Chrome插件Lighthouse檢查 PWA 配置是否生效以及配置是否正確。

    • 打開博客頁面
    • 啟動Lighthouse插件 (Lighthouse插件要求至少包含一個 512*512 像素的圖標)

關於 PWA（漸進式增強 Web 應用）的更多內容請參閲 Google Tools for Web Developers

字數統計

要為Butterfly配上字數統計特性, 你需要如下幾個步驟:

  1. 打開 hexo 工作目錄

  2. npm install hexo-wordcount --save or yarn add hexo-wordcount

  3. 修改 主題配置文件:

1
2
3
4
5
wordcount:
  enable: true
  post_wordcount: true
  min2read: true
  total_wordcount: true


圖片大圖查看模式

只能開啟一個

修改 主題配置文件

1
2
# fancybox http://fancyapps.com/fancybox/3/
fancybox: true

fancybox.gif

修改 主題配置文件

1
medium_zoom: true

medium_zoom.gif

Snackbar 彈窗

Snackbar 彈窗,根據自己愛好開啟

修改 主題配置文件

1
2
3
4
5
6
7
8
9
# Snackbar 彈窗
# https://github.com/polonel/SnackBar
# position 彈窗位置
# 可選 top-left / top-center / top-right / bottom-left / bottom-center / bottom-right
snackbar:
  enable: true
  position: bottom-left
  bg_light: '#49b1f5' #light mode時彈窗背景
  bg_dark: '#2d3035' #dark mode時彈窗背景

未開啟Snackbar

snackbar_false.gif

開啟Snackbar

snackbar_true.gif

其它配置

CSS 前綴

有些 CSS 並不是所有瀏覽器都支持，需要增加對應的前綴才會生效。

開啟 css_prefix 後，會自動為一些 CSS 增加前綴。（會增加 20%的體積）

修改配置文件

1
2
# Add the vendor prefixes to ensure compatibility
css_prefix: true

Open Graph

在 head 裏增加一些 meta 資料，例如縮略圖、標題、時間等等。當你分享網頁到一些平台時，平台會讀取 Open Graph 的內容，展示縮略圖，標題等等信息。

修改配置文件

1
2
3
# Open graph meta tags
# https://developers.facebook.com/docs/sharing/webmasters/
Open_Graph_meta: true

Instantpage

當鼠標懸停到鏈接上超過 65 毫秒時，Instantpage 會對該鏈接進行預加載，可以提升訪問速度。

修改配置文件

1
2
3
# https://instant.page/
# prefetch (預加載)
instantpage: true

Pangu

如果你跟我一樣，每次看到網頁上的中文字和英文、數字、符號擠在一塊，就會坐立難安，忍不住想在它們之間加個空格。這個外掛正是你在網路世界走跳所需要的東西，它會自動替你在網頁中所有的中文字和半形的英文、數字、符號之間插入空白。

修改配置文件

1
2
3
4
5
# https://github.com/vinta/pangu.js
# Insert a space between Chinese character and English character (中英文之間添加空格)
pangu:
  enable: false
  field: post # site/post

field只支持兩個參數，post(只在文章頁生效)和site(全站生效)

Pjax

當用户點擊鏈接，通過ajax更新頁面需要變化的部分，然後使用HTML5的pushState修改瀏覽器的URL地址。

這樣可以不用重複加載相同的資源（css/js）， 從而提升網頁的加載速度。

1
2
3
4
5
6
7
8
# Pjax [Beta]
# It may contain bugs and unstable, give feedback when you find the bugs.
# https://github.com/MoOx/pjax
pjax: 
  enable: true
  exclude:
    - /music/
    - /no-pjax/

對於一些第三方插件，有些並不支持 pjax 。
你可以把網頁加入到 exclude 裏，這個網頁會被 pjax 排除在外。
點擊該網頁會重新加載網站

使用pjax後，一些自己DIY的js可能會無效，跳轉頁面時需要重新調用，請參考Pjax文檔
使用pjax後，一些個別頁面加載的js/css，將會改為所有頁面都加載

Butterfly的Pjax目前仍有一些問題，請留意

  • 使用谷歌廣告可能會報錯（例如自動廣告）

如果你在使用中發現問題，歡迎反饋Bugs

Inject

2.3.0以上支持

如想添加額外的js/css/meta等等東西，可以在Inject裏添加，支持添加到head(</body>標籤之前)和bottom(</html>標籤之前)。

請注意：以標準的html格式添加內容

例如

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

留意: 如果你的網站根目錄不是’/',使用本地圖片時，需加上你的根目錄。
例如：網站是 https://yoursite.com/blog,引用css/xx.css，則設置為<link rel="stylesheet" href="/blog/css/xx.css">

CDN

配置文件中最後一部分CDN，裏面是主題所引用到的文件，可自行配置CDN。（非必要請勿修改，配置後請確認鏈接是否能訪問）

以下是一些CDN提供商：

❓ Butterfly 安裝文檔(五) 主題問答