目錄
  1. 1. 快速開始
    1. 1.1. 主題安裝和升級
      1. 1.1.1. 安裝
      2. 1.1.2. 應用主題
      3. 1.1.3. 平滑升級
  2. 2. 主題頁面
    1. 2.1. Page Front-matter
    2. 2.2. Post Front-matter
    3. 2.3. 標籤頁
    4. 2.4. 分類頁
    5. 2.5. 相冊
      1. 2.5.1. 創建相冊頁
    6. 2.6. 友情鏈接
      1. 2.6.1. 創建友情鏈接頁面
      2. 2.6.2. 友情鏈接添加
      3. 2.6.3. 友情鏈接界面設置
  3. 3. 配置
    1. 3.1. 配置文件説明
    2. 3.2. 語言
    3. 3.3. 導航菜單
    4. 3.4. 代碼
      1. 3.4.1. 代碼高亮主題
      2. 3.4.2. 代碼複製
      3. 3.4.3. 代碼框展開/關閉
      4. 3.4.4. 代碼換行
    5. 3.5. 社交圖標
    6. 3.6. 主頁文章節選(自動節選和文章頁description)
    7. 3.7. 頂部圖
      1. 3.7.1. page頁
        1. 3.7.1.1. 當具體url時
        2. 3.7.1.2. 當頂部圖留空,true和false
      2. 3.7.2. post頁
    8. 3.8. 文章相關項
    9. 3.9. 文章版權
    10. 3.10. 文章打賞
    11. 3.11. 文章封面
    12. 3.12. 頭像
    13. 3.13. TOC
      1. 3.13.1. 為特定的文章配置是否顯示TOC和特定的目錄章節數字
      2. 3.13.2. 設置是否自動打開TOC
    14. 3.14. 相關文章
    15. 3.15. Footer 設置
      1. 3.15.1. 博客年份
      2. 3.15.2. 頁腳自定義文本
      3. 3.15.3. ICP
    16. 3.16. 右下角按鈕
      1. 3.16.1. 簡繁轉換
      2. 3.16.2. 夜間模式
      3. 3.16.3. 閲讀模式
    17. 3.17. 側邊欄設置
      1. 3.17.1. 側邊排版
      2. 3.17.2. 訪問人數 busuanzi (UV 和 PV)
      3. 3.17.3. 運行時間
    18. 3.18. Note (Bootstrap Callout)
      1. 3.18.1. 配置
      2. 3.18.2. 用法
    19. 3.19. 評論
      1. 3.19.1. Disqus
      2. 3.19.2. Laibili(來必力)
      3. 3.19.3. Gitment
      4. 3.19.4. Gitalk
      5. 3.19.5. Valine
    20. 3.20. 分享
      1. 3.20.1. AddThis
      2. 3.20.2. Sharejs
      3. 3.20.3. Addtoany
    21. 3.21. 搜索系統
      1. 3.21.1. Algolia
      2. 3.21.2. 本地搜索
    22. 3.22. 網站驗證
    23. 3.23. 分析統計
      1. 3.23.1. 百度統計
      2. 3.23.2. 谷歌分析
    24. 3.24. MathJax
    25. 3.25. KaTeX
    26. 3.26. 美化/特效
      1. 3.26.1. 自定義主題色
      2. 3.26.2. 網站背景
      3. 3.26.3. footer 背景
      4. 3.26.4. 打字效果
      5. 3.26.5. 靜止彩帶
      6. 3.26.6. 動態彩帶
      7. 3.26.7. canvas-nest
      8. 3.26.8. 鼠標點擊 (煙花效果)
      9. 3.26.9. 文章頁美化
      10. 3.26.10. 自定義字體
      11. 3.26.11. 網站副標題
      12. 3.26.12. 主頁top_img顯示大小
    27. 3.27. PWA
    28. 3.28. 字數統計
    29. 3.29. 文章置頂
  4. 4. Q & A
hexo-theme-butterfly安裝文檔

如果你對主題安装有疑問或者發現bugs,請點擊這裏反饋/詢問

本教程更新于2019年9月27日

快速開始

hexo-theme-butterfly是基於Molunerfinnhexo-theme-melody的基礎上進行開發的。
文檔也是在hexo-theme-melody的文檔基礎上修改。因為一些配置變更導致與原主題配置上有部分區別。故如果安裝hexo-theme-butterfly主題,請參考這篇文檔。

主題安裝和升級

安裝

在你的博客根目錄裏

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

如果想要安裝比較新的dev分支,可以

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

應用主題

修改站點配置文件_config.yml,把主題改為Butterfly

1
theme: Butterfly

如果你沒有 pug 以及 stylus 的渲染器,請下載安裝: npm install hexo-renderer-jade hexo-renderer-stylus --save or yarn add hexo-renderer-jade hexo-renderer-stylus

平滑升級

為了主題的平滑升級, Butterfly 使用了 data files特性。

推薦把主題默認的配置文件_config.yml複製到 Hexo 工作目錄下的source/_data/butterfly.yml,如果source/_data的目錄不存在那就創建一個。

注意,如果你創建了butterfly.yml, 它將會替換主題默認配置文件_config.yml裏的配置項 (不是合併而是替換), 之後你就只需要通過git pull的方式就可以平滑地升級 theme-butterfly了。

主題頁面

Page Front-matter

1
2
3
4
5
6
7
8
---
title:
date:
type: (tags,link,categories這三個頁面需要配置)
comments: (是否需要顯示評論,默認true)
description:
top_img: (設置頂部圖)
---

Post Front-matter

1
2
3
4
5
6
7
8
9
10
11
12
13
14
---
title:
date:
tags:
categories:
keywords:
description:
top_img: (除非特定需要,可以不寫)
comments 是否顯示評論(除非設置false,可以不寫)
cover: 縮略圖
toc: 是否顯示toc (除非特定文章設置,可以不寫)
toc_number: 是否顯示toc數字 (除非特定文章設置,可以不寫)
copyright: 是否顯示版權 (除非特定文章設置,可以不寫)
---

標籤頁

  1. 前往你的 Hexo 博客的根目錄

  2. 輸入hexo new page tags

  3. 你會找到source/tags/index.md這個文件

  4. 修改這個文件:

1
2
3
4
5
---
title: 標籤
date: 2018-01-05 00:00:00
type: "tags"
---

分類頁

  1. 前往你的 Hexo 博客的根目錄

  2. 輸入hexo new page categories

  3. 你會找到source/categories/index.md這個文件

  4. 修改這個文件:

1
2
3
4
5
---
title: 分類
date: 2018-01-05 00:00:00
type: "categories"
---

相冊

為你的博客創建一個相冊頁!

創建相冊頁

  1. 前往你的 Hexo 博客的根目錄

  2. 輸入hexo new page gallery

  3. 你會找到source/gallery/index.md這個文件

  4. 修改這個文件:

1
2
3
4
5
---
title: Gallery
date: 2018-01-05 00:00:00
type: "gallery"
---

Butterfly 提供了一個叫做gallery的標籤,讓你能夠在 markdown 文件裏生成gallery-item

修改你剛剛創建的source/gallery/index.md,並加上gallery 標籤。

gallery img-url [title]

例子:

1
2
3
4
5
6
7
8
9
10
11
---
title: Gallery
date: 2018-01-05 00:00:00
type: "gallery"
---
{% gallery https://ws1.sinaimg.cn/large/8700af19gy1fp5i6o2vghj20ea0eajse melody %}
{% gallery https://user-images.githubusercontent.com/12621342/37325500-23e8f77c-26c9-11e8-8e24-eb4346f1fff5.png background %}
{% gallery https://ws1.sinaimg.cn/large/8700af19gy1fp5i64zaxqj20b40b474b demo1 %}
{% gallery https://ws1.sinaimg.cn/large/8700af19ly1fn2h26q32uj21120kudqq demo2 %}
{% gallery https://ws1.sinaimg.cn/large/8700af19ly1fnhdaimi40j218g0p0dic demo3 %}
{% gallery https://ws1.sinaimg.cn/large/8700af19ly1fn2i5kjh2pj21120kuncd %}

gallery-item 也擁有 fancybox 的效果!

友情鏈接

為你的博客創建一個友情鏈接!

創建友情鏈接頁面

  1. 前往你的 Hexo 博客的根目錄
  2. 輸入 hexo new page link
  3. 你會找到source/link/index.md這個文件
  4. 修改這個文件:
1
2
3
4
5
---
title: 友情鏈接
date: 2018-06-07 22:17:49
type: "link"
---

友情鏈接添加

在Hexo博客目錄中的source/_data,創建一個文件link.yml

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
class:
class_name: 友情鏈接
link_list:
1:
name: xxx
link: https://blog.xxx.com
avatar: https://cdn.xxxxx.top/avatar.png
descr: xxxxxxx
2:
name: xxxxxx
link: https://www.xxxxxxcn/
avatar: https://xxxxx/avatar.png
descr: xxxxxxx

class2:
class_name: 鏈接無效
link_list:
1:
name: 夢xxx
link: https://blog.xxx.com
avatar: https://xxxx/avatar.png
descr: xxxx
2:
name: xx
link: https://www.axxxx.cn/
avatar: https://x
descr: xx

友情鏈接界面設置

需要添加友情鏈接,可以在Butterfly.yml配置
可在友情鏈接上寫上自己的個人資料,方便其他人添加。

1
2
3
4
5
6
7
8
Flink:
headline: 友情鏈接
info_headline: 我的Blog資料
name: Blog 名字: JerryC
address: Blog 地址: https://jerryc.me/
avatar: Blog 頭像: https://jerryc.me/img/avatar.png
info: Blog 簡介: 今日事,今日畢
comment: 如果需要交換友鏈,請留言


配置

配置文件説明

  • 站點配置文件_config.yml是 hexo 工作目錄下的主配置文件
  • butterfly.ymlButterfly 的配置文件。它需要你手動將主題目錄下的_config.yml文件複製到 hexo 工作目錄的source/_data/butterfly.yml中。如果文件或者文件夾不存在,需要手動創建。

語言

修改站點配置文件 _config.yml

默認語言是 en

主題支持三種語言

  • default(en)
  • zh-CN (簡體中文)
  • zh-TW (繁體中文)

導航菜單

配置butterfly.yml

1
2
3
4
5
6
7
8
9
10
menu:
Home: / || fa fa-home
Archives: /archives/ || fa fa-archive
Tags: /tags/ || fa fa-tags
Categories: /categories/ || fa fa-folder-open
Link: /link/ || fa fa-link
About: /about/ || fa fa-heart
List||fa fa-list:
- Music || /music/ || fa fa-music
- Movie || /movies/ || fa fa-film

必須是 /xxx/,後面||分開,然後寫圖標名。菜單名稱可自己修改

格式:

顯示名稱:

路徑||icon

sub-menu格式

名稱||icon:

  • 名稱 || 路徑 || icon

代碼

代碼高亮主題

Butterfly 支持了 Material Theme全部 5 種代碼高亮樣式:

  • default
  • darker
  • pale night
  • light
  • ocean

配置butterfly.yml

1
highlight_theme: light

default

darker

pale night

light

ocean

代碼複製

主題支持代碼複製功能

配置butterfly.yml

1
highlight_copy: true

代碼框展開/關閉

在默認情況下,代碼框自動展開,可設置是否所有代碼框都關閉狀態,點擊>可展開代碼

配置butterfly.yml

1
highlight_shrink: true #代碼框不展開,需點擊 '>' 打開

highlight_shrink: true

highlight_shrink: false

代碼換行

在默認情況下,hexo-highlight在編譯的時候不會實現代碼自動換行。如果你不希望在代碼塊的區域裏有橫向滾動條的話,那麼你可以考慮開啟這個功能。

配置butterfly.yml

1
code_word_wrap: true

然後找到你站點的 Hexo 配置文件_config.yml,將line_number改成false:

1
2
3
4
5
highlight:
enable: true
line_number: false
auto_detect: false
tab_replace:

設置code_word_wrap之前:

設置code_word_wrap之後:

社交圖標

Butterfly支持 font-awesome v4font-awesome v5. 如需開啟font-awesome v5,需要在Butterfly.yml上開啟

1
2
3
4
cdn:
css:
fontawesome: https://cdn.jsdelivr.net/npm/font-awesome@latest/css/font-awesome.min.css
fontawesomeV5: https://use.fontawesome.com/releases/v5.8.1/css/all.css

無論V4還是V5,書寫格式都是一樣的圖標名:url

1
2
3
social:
fa fa-github: https://github.com/jerryc127
fa fa-rss: /atom.xml

圖標名可在這尋找

PC:

Mobile:

1560603353743

主頁文章節選(自動節選和文章頁description)

因為主題UI的關係,主頁文章節選只支持自動節選文章頁description。優先選擇自動節選

butterfly.yml裏可以開啟auto_excerpt的選項,你的文章將會在自動截取部分顯示在主頁。(默認顯示150個字)。

1
2
3
auto_excerpt:
enable: true
length: 150

如果沒有開啟自動節選,則會顯示文章頁front-matter裏面設置的description

注意:如果開啟了自動節選功能,代碼塊的顯示將有可能不正常。

頂部圖

頂部圖有2種配置:具體url 和(留空,true和false,三個效果一樣)

page頁

當具體url時

主頁的頂部圖可以在Butterfly.yml設置top_img

archives頁的頂部圖可以在Butterfly.yml設置archive_img

其他page頁的頂部圖可以在各自的md頁面設置front-matter中的top_img

主頁外,其他頁面如果沒有設置各自的top_img,則會顯示與主頁同樣的top_img圖片

當頂部圖留空,true和false

主頁會顯示純顏色的頂部圖

其他page的頂部圖沒有設置時,也會顯示純顏色的頂部圖

post頁

post頁的頂部圖會優先顯示各自front-matter中的top_img,如果沒有設置,則會縮略圖(即各自front-matter中的cover),如果沒有則會顯示默認的post頂部圖,可在Butterfly.yml設置post_img

文章相關項

這個選項是用來顯示文章的相關信息的。

配置butterfly.yml

1
2
3
4
post_meta:
date_type: both #or created or updated 文章日期是創建日或者更新日或都顯示
categories: true # or false 是否顯示分類
tags: true # or false 是否顯示標籤

在文章頂部的資料,

date_type: 可設置文章日期顯示創建日期(created)或者更新日期(updated)或者兩種都顯示(both)

categories 是否顯示分類

tags是否顯示標籤

文章版權

為你的博客文章展示文章版權和許可協議。

配置butterfly.yml

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

如果有文章(例如:轉載文章)不需要顯示版權,可以在文章Front-matter單獨設置

1
copyright: false

版權顯示截圖

文章打賞

在你每篇文章的結尾,可以添加打賞按鈕。相關二維碼可以自行配置

配置butterfly.yml

1
2
3
4
5
6
7
8
9
reward:
enable: true
QR_code:
- itemlist:
img: /img/wechat.jpg
text: 微信
- itemlist:
img: /img/alipay.jpg
text: 支付寶

文章封面

文章的markdown文檔上,在Front-matter添加cover,并填上要顯示的圖片地址。
如果不配置cover,可以設置顯示默認的cover.

配置butterfly.yml

1
default_cover: https://cdn.jsdelivr.net/gh/jerryc127/CDN@latest/cover/default_bg.png

當配置多張圖片時,會隨機選擇一張作爲cover.此時寫法應爲

1
2
3
4
default_cover:
- https://cdn.jsdelivr.net/gh/jerryc127/CDN@latest/cover/default_bg.png
- https://cdn.jsdelivr.net/gh/jerryc127/CDN@latest/cover/default_bg2.png
- https://cdn.jsdelivr.net/gh/jerryc127/CDN@latest/cover/default_bg3.png


頭像

配置butterfly.yml

1
avatar: https://xxxx/avatar.png

TOC

在文章頁,會有一個目錄,用於顯示TOC。 手機端默認顯示按鈕。

配置butterfly.yml

1
2
3
toc:
enable: true
number: true #顯示章節數字

PC

Mobile

為特定的文章配置是否顯示TOC和特定的目錄章節數字

在你的文章md文件的頭部,加入toc_numbertoc項,並配置true或者false即可。

toc是否顯示文章TOC

toc_number 是否顯示章節數

配置之後你的特定的文章將會擁有它自己的目錄數字的顯示與否,而不會受全局的配置影響。

enable: true

number: false

設置是否自動打開TOC

可選擇進入文章頁面時,是否自動打開sidebar顯示TOC

1
2
auto_open_sidebar:
enable: true

相關文章

相關文章推薦的原理是根據文章tags的比重來推薦

配置butterfly.yml

1
2
3
related_post:
enable: true
limit: 6 # 顯示推薦文章數目

博客年份

since是一個來展示你站點起始時間的選項。它位於頁面的最底部。

配置butterfly.yml

1
since: 2018

頁腳自定義文本

footer_custom_text是一個給你用來在頁腳自定義文本的選項。通常你可以在這裏寫聲明文本等。支持 HTML。

配置butterfly.yml

1
footer_custom_text: Hi, welcome to my <a href="https://jerryc.me/">blog</a>!

ICP

對於部分有備案的域名,可以在ICP配置顯示。

配置butterfly.yml

1
2
3
4
5
ICP:
enable: true
url: http://www.beian.miit.gov.cn/state/outPortal/loginPortal.action
text: 粵ICP備xxxx
icon: /img/icp.png

右下角按鈕

簡繁轉換

簡體繁體互換

右下角會有簡繁轉換按鈕。

配置butterfly.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
translate:
enable: true
# 默認按鈕顯示文字(網站是簡體,應設置為'default: 繁')
default:
#網站默認語言,1: 繁體中文, 2: 簡體中文
defaultEncoding: 1
#延遲時間,若不在前, 要設定延遲翻譯時間, 如100表示100ms,默認為0
translateDelay: 0
#博客網址
cookieDomain: "https://jerryc.me/"
#當文字是簡體時,按鈕顯示的文字
msgToTraditionalChinese: "繁"
#當文字是繁體時,按鈕顯示的文字
msgToSimplifiedChinese: "簡"

簡體

繁體

夜間模式

右下角會有夜間模式按鈕

配置butterfly.yml

1
2
nightshift:
enable: true

閲讀模式

閲讀模式下會去掉除文章外的內容,避免干擾閲讀。

只會出現在文章頁面,右下角會有閲讀模式按鈕。

配置butterfly.yml

1
2
readmode:
enable: true

側邊欄設置

側邊排版

可自行決定哪個項目需要顯示,可決定位置。

至少需要顯示一個

配置butterfly.yml

1
2
3
4
5
6
7
8
9
aside:
position: right # left or right
card_author: true
card_announcement: true
card_recent_post: true
card_categories: true
card_tags: true
card_archives: true
card_webinfo: true

left

right

訪問人數 busuanzi (UV 和 PV)

訪問 busuanzi 的官方網站查看更多的介紹。

配置butterfly.yml

1
2
3
4
busuanzi:
site_uv: true
site_pv: true
page_pv: true

運行時間

網頁已運行時間

配置butterfly.yml

1
2
3
4
5
6
runtimeshow:
enable: true
start_date: 6/7/2018 00:00:00
##網頁開通時間
#格式: 月/日/年 時間
#也可以寫成 年/月/日 時間

Note (Bootstrap Callout)

移植於next主題(注意,書寫不是markdown規範,而是hexo特有的功能,故在其它地方會顯示不出效果)

配置

配置butterfly.yml

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
4
5
6
7
8
{% note [class] [no-icon] %}
Any content (support inline tags too.io).
{% endnote %}

[class] : default | primary | success | info | warning | danger.
[no-icon] : Disable icon in note.

All parameters are optional.

具體效果、用法可查看這裏

評論

只能選擇一個評論服務商

Disqus

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

配置butterfly.yml

1
2
3
disqus:
enable: true # or false
shortname: 你的disqus的 short-name

Laibili(來必力)

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

配置butterfly.yml

1
2
3
laibili:
enable: true # or false
uid: 你的laibili的uid

laibili 的 uid 你能在這裏找到:

Gitment

遵循 gitment的指示去獲取你的 github Oauth 應用的 client id 和 secret 值。

然後配置butterfly.yml:

1
2
3
4
5
6
gitment:
enable: true # or false
owner: 你的github用户名
repo: 你的github倉庫
client_id: 你的client id
client_secret: 你的client secret

Gitalk

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

然後配置butterfly.yml:

1
2
3
4
5
6
7
gitalk:
enable: true
client_id: 你的client id
client_secret: 你的client secret
repo: 你的github倉庫
owner: 你的github用户名
admin: 該倉庫的擁有者或協作者

Valine

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

然後配置butterfly.yml:

1
2
3
4
5
6
7
8
9
10
11
valine:
enable: false # if you want use valine,please set this value is true
appId: # leancloud application app id
appKey: # leancloud application app key
notify: false # valine mail notify (true/false) https://github.com/xCss/Valine/wiki
verify: false # valine verify code (true/false)
pageSize: 10 # comment list page size
avatar: monsterid # gravatar style https://valine.js.org/#/avatar
lang: en # i18n: zh-cn/en/tw
placeholder: Please leave your footprints # valine comment input placeholder(like: Please leave your footprints )
guest_info: nick,mail,link #valine comment header inf

分享

只能選擇一個分享服務商

AddThis

找到你的 pub-id

配置butterfly.yml

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

Sharejs

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

配置butterfly.yml

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

Addtoany

可以到addtoany查看使用説明

1
2
3
4
5
6
7
8
9
10
addtoany:
enable: false
item: # 顯示的內容
- facebook
- twitter
- wechat
- sina_weibo
- facebook_messenger
- email
- copy_link

搜索系統

Algolia

  1. 你需要安裝 hexo-algoliahexo-algoliasearch. 根據它們的説明文檔去做相應的配置。

  2. 配置butterfly.yml

1
2
3
4
5
6
7
8
9
algolia_search:
enable: true
hits:
per_page: 6

labels:
input_placeholder: Search for Posts
hits_empty: "We didn't find any results for the search: ${query}" # if there are no result
hits_stats: "${hits} results found in ${time} ms"

本地搜索

  1. 你需要安裝 hexo-generator-search. 根據它的文檔去做相應配置。注意格式只支持 xml

  2. 配置butterfly.yml

1
2
3
4
5
local_search:
enable: false
labels:
input_placeholder: Search for Posts
hits_empty: "We didn't find any results for the search: ${query}" # if there are no result

網站驗證

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

配置butterfly.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# Google Webmaster tools verification setting
# See: https://www.google.com/webmasters/
google_site_verification:

# Bing Webmaster tools verification setting
# See: https://www.bing.com/webmaster/
bing_site_verification:

# Yandex Webmaster tools verification setting
# See: https://webmaster.yandex.ru/
yandex_site_verification:

# Baidu Webmaster tools verification setting
# See: https://ziyuan.baidu.com/site/
baidu_site_verification:

# 360 Webmaster tools verification setting
# see http://zhanzhang.so.com/
qihu_site_verification:

分析統計

百度統計

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

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

  1. 配置butterfly.yml
1
baidu_analytics: 你的代碼

谷歌分析

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

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

  1. 配置butterfly.yml
1
google_analytics: 你的代碼 # 通常以`UA-`打頭

MathJax

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

配置butterfly.yml:

1
2
3
mathjax:
enable: true # or false
cdn: https://cdn.bootcss.com/mathjax/2.7.2/MathJax.js?config=TeX-AMS-MML_HTMLorMML # required

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

查看: hexo-renderer-kramed

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

效果:

KaTeX

首先禁用MathJax(如果你配置過 MathJax 的話),然後修改你的butterfly.yml以便加載katex.min.css:

1
2
3
4
katex:
enable: true
cdn:
css: https://cdn.jsdelivr.net/npm/katex@latest/dist/katex.min.css

你不需要添加katex.min.js來渲染數學方程。相應的你需要卸載你之前的 hexo 的 markdown 渲染器以及hexo-math,然後安裝新的hexo-renderer-markdown-it-plus:

1
2
3
4
5
6
7
8
9
10
11
12
13
# 替換 `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-math`
npm un hexo-math --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 默認添加了 Copy As TeX Code的功能。

美化/特效

自定義主題色

可以修改大部分UI顏色

配置butterfly.yml,比如:

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

1
2
3
4
5
6
7
8
9
theme_color:
enable: true
main: "#9370DB"
paginator: "#7A7FF1"
button_hover: "#FF7242"
text_selection: "#69c46d"
link_color: "#858585"
hr_color: "#A4D8FA"
read-mode-bg_color: '#FAF9DE'


網站背景

默認顯示白色,可設置圖片或者顔色

配置butterfly.yml

1
2
3
4
# 圖片格式 background: url(http://xxxxxx.com/xxx.jpg)
# 顔色 background: '#49B202'
# 留空 顯示白色
background:

background:'#49B202'

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

footer 的背景會與top_img的一致, 當設置false時,將與主題色一致。

配置butterfly.yml

1
2
# footer是否顯示圖片背景(與top_img一致)
footer_bg: true

true

打字效果

打字效果activate-power-mode

配置butterfly.yml

1
2
activate_power_mode:
enable: true

靜止彩帶

好看的彩帶背景,可設置每次刷新更換彩帶,或者每次點擊更換彩帶

配置butterfly.yml

1
2
3
4
5
6
canvas_ribbon:
enable: false
size: 150
alpha: 0.6
zIndex: -1
click_to_change: false #設置是否每次點擊都更換彩帶

相關配置可查看canvas_ribbon

動態彩帶

好看的彩帶背景,會飄動

配置butterfly.yml

1
2
canvas_ribbon_piao:
enable: true

canvas-nest

配置butterfly.yml

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.
script: https://cdn.jsdelivr.net/gh/jerryc127/CDN/js/canvas-nest.js # or /js/third-party/canvas-nest.js

鼠標點擊 (煙花效果)

配置butterfly.yml

1
2
fireworks:
enable: true

文章頁美化

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

配置butterfly.yml

1
2
3
4
post_beautify:
enable: true
title-prefix-icon: '\f0c1'
title-prefix-icon-color: "#F47466"

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

未開啓美化

開啓美化

自定義字體

可自行設置字體的font-family

配置butterfly.yml

1
2
3
4
font:
enable: true
font-family: Lato, Helvetica Neue For Number, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, PingFang SC, Hiragino Sans GB,"Microsoft JhengHei", "MicrMicrosoft YaHei", Helvetica Neue, Helvetica, Arial, sans-serif
code-font: consolas, Menlo, "PingFang SC", "Microsoft JhengHei","Microsoft YaHei", monospace, Helvetica Neue For Number

網站副標題

適用於 版本號 >= V1.2.0

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

配置butterfly.yml

1
2
3
4
5
6
7
8
# 主頁subtitle
# 打字效果
# (如果有英文逗號' , ',請使用轉義字符 &#44;)
subtitle:
enable: true
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
2
index_site_info_top: 40%
index_top_img_height: 400px

效果

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. butterfly.yml中開啟 pwa 選項。
1
2
3
4
5
6
7
8
pwa:
enable: true
manifest: /img/pwa/manifest.json
theme_color: "#fff"
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",//首選顯示模式 其他選項有:fullscreen,minimal-ui,browser
"scope": "/",
"start_url": "/",
"icons": [ //該數組指定icons圖標參數,用來時適配不同設備(需為png,至少包含一個192px*192px的圖標)
{
"src": "images/pwaicons/36.png", //圖標文件的目錄,需在source/目錄下自行創建。
"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. 配置butterfly.yml:

1
2
wordcount:
enable: true

文章置頂

要為你一些文章置頂,你需要如下步驟:

  1. 打開 hexo 工作目錄
  2. npm uninstall hexo-generator-index --save 然後 npm install hexo-generator-index-pin-top --save
  3. 你要在文章的front-matter區域裏添加top: True屬性來把這篇文章置頂。
  4. 你可以參考 hexo-generator-index-pin-top這個倉庫來了解更多細節。

舉個例子:

你的某篇文章開頭如下:

1
2
3
4
5
6
title: xxxx
tags:
- xxx
date: 2018-08-08 08:08:08
---
// ....

現在把top: True加進去:

1
2
3
4
5
6
7
title: xxxx
tags:
- xxx
date: 2018-08-08 08:08:08
top: True
---
// ....

Q & A

Q. 頁面只顯示 extends includes/layout.pug block content #recent-posts.recent-posts include includes/recent-posts.pug include includes/pagination.pug #aside_content.aside_content include includes/aside.pug

A. 请下载安装:npm install hexo-renderer-jade hexo-renderer-stylus --save or yarn add hexo-renderer-jade hexo-renderer-stylus

Q. 報錯

1
2
3
4
5
6
7
8
9
10
ERROR C:\Users\Shawn\Desktop\Blog\themes\Butterfly\layout\includes\layout.pug:18
16|
17| - var pageDescription = page.description || page.title || config.description || ‘’

18| - var pageKeywords = (config.keywords || []).join(‘,’)
19| - if (page.tags && page.tags.data) pageKeywords = page.tags.data.map(function(tag) {return tag.name;}).join(‘,’)
20| - var pageAuthor = config.email ? config.author + ‘,’ + config.email : config.author
21| - var pageCopyright = config.copyright || config.author

(config.keywords || []).join is not a function

A: 在Hexo的 _config文檔裏的keywords改成一下形式

1
keywords: [Jerry,JerryC,blog,安卓博客,安卓,程序员,个人博客,安卓開發,安卓博客,程序員,安卓開發,個人博客,Android]

Q: 配置友情鏈接頁面時出現報錯

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
ERROR D:\Desktop\orxing-blog\themes\Butterfly\layout\flink.pug:2
1| .flink
> 2| each i in site.data.link
3| p.comment-word= i.class_name
4| .post-cards
5| ul.md-links

Cannot read property 'length' of undefined
TypeError: D:\Desktop\orxing-blog\themes\Butterfly\layout\flink.pug:2
1| .flink
> 2| each i in site.data.link
3| p.comment-word= i.class_name
4| .post-cards
5| ul.md-links

Cannot read property 'length' of undefined
at eval (eval at wrap (D:\Desktop\orxing-blog\node_modules\pug-runtime\wrap.js:6:10), <anonymous>:1890:32)
at eval (eval at wrap (D:\Desktop\orxing-blog\node_modules\pug-runtime\wrap.js:6:10), <anonymous>:2017:4)
at template (eval at wrap (D:\Desktop\orxing-blog\node_modules\pug-runtime\wrap.js:6:10), <anonymous>:10152:72)
at Theme._View.View._compiled (D:\Desktop\orxing-blog\node_modules\hexo\lib\theme\view.js:123:48)
at Theme._View.View.View.render (D:\Desktop\orxing-blog\node_modules\hexo\lib\theme\view.js:29:15)
at D:\Desktop\orxing-blog\node_modules\hexo\lib\hexo\index.js:349:21
at tryCatcher (D:\Desktop\orxing-blog\node_modules\bluebird\js\release\util.js:16:23)
at D:\Desktop\orxing-blog\node_modules\bluebird\js\release\method.js:15:34
at RouteStream._read (D:\Desktop\orxing-blog\node_modules\hexo\lib\hexo\router.js:123:3)
at RouteStream.Readable.read (_stream_readable.js:457:10)
at resume_ (_stream_readable.js:936:12)
at processTicksAndRejections (internal/process/task_queues.js:84:9)

A: 請檢查 link.yml文檔内代碼的空格

Q: 升級最新版本hexo g後報錯

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
INFO  Deleted database.
INFO Start processing
FATAL Something's wrong. Maybe you can find the solution here: https://hexo.io/docs/troubleshooting.html
TypeError: Cannot read property 'enable' of undefined
at Hexo.<anonymous> (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/themes/Butterfly/scripts/post-lazyload.js:5:23)
at Hexo.tryCatcher (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/util.js:16:23)
at Hexo.<anonymous> (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/method.js:15:34)
at /Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/hexo/lib/extend/filter.js:60:50
at tryCatcher (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/util.js:16:23)
at Object.gotValue (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/reduce.js:155:18)
at Object.gotAccum (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/reduce.js:144:25)
at Object.tryCatcher (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/util.js:16:23)
at Promise._settlePromiseFromHandler (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/promise.js:517:31)
at Promise._settlePromise (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/promise.js:574:18)
at Promise._settlePromiseCtx (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/promise.js:611:10)
at _drainQueueStep (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/async.js:142:12)
at _drainQueue (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/async.js:131:9)
at Async._drainQueues (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/async.js:147:5)
at Immediate.Async.drainQueues [as _onImmediate] (/Users/qinkangdeid/Nextcloud/work/codes/personal/github/personal/qinkangdeid.github.io/node_modules/bluebird/js/release/async.js:17:14)
at processImmediate (internal/timers.js:439:21)

A: 請參照最新版的_config.xml, 比對后,把缺的配置複製到butterfly.xml去

文章作者: JerryC
文章鏈接: https://jerryc.me/posts/21cfbf15/
版權聲明: 本博客所有文章除特別聲明外,均採用 CC BY-NC-SA 4.0 許可協議。轉載請註明來自 JerryC
打賞
  • 微信
  • 支付寶

評論