环境准备

软件安装

安装git, Node.js, npm
查看是否安装成功：

1
2
3
node -v
npm -v
git --version

创建github pages仓库

新建一个仓库，取名为[name].github.io

基本安装

新建一个文件夹，比如cmander_site，然后进入之
安装Hexo

1
2
npm install -g
hexo-cli

安装完成后初始化和安装所需组件

1
2
hexo init       # 初始化，注意此时文件夹需要是空的
npm install     # 安装组件

完成后输入经典Hexo三连

1
hexo clean && hexo generate && hexo server

默认会在http://localhost:4000 生成一个landscape主题的页面，此时本地博客安装成功。

拉取butterfly仓库

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

进入 Hexo 文件夹，修改根目录下的_config.yml：

1
theme: butterfly

安装渲染插件

1
npm install hexo-renderer-pug hexo-renderer-stylus --save

一个比较推荐的操作是，创建一个_config.buttefly.yml，并复制_config.yml 中的所有内容进去。Hexo 会自动合并二者的内容，且绝大部分的设置以_config.butterfly.yml 为优先，未来可以只在_config.buttefly.yml 中配置。

注：不要把_config.yml 删掉，部分内容仍然需要在这里面配置！

Hexo 常见命令可以参考 这篇文章。

简单配置一下 config 文件：

1
2
3
4
5
6
7
8
# Site
title: 无声之地
subtitle: ''
description: 于无声处且行吟
keywords:
author: CMander
language: zh-CN
timezone: Asia/Shanghai

易用性设置

博客文件的生成配置

Hexo的post，使用hexo n "[name]"创建时，是只会在source/post下面生成一个 [name].md的，不便于文章的排序（本地）和查找。为此可以通过修改配置文件的new_post_name来完成。

修改_config.yml：

1
new_post_name: :year-:month-:day_:title.md # File name of new posts

再生成文章，就是形如 20140514_name.md 的格式了。

为博客文章生成永久链接

参考 Ordis 的文章 Hexo 博客生成永久链接

Hexo 的默认文章链接是形如: year/:month/:day/:title 格式的。这样会导致生成链接的时候 title 生成一大串，如果是中文标题的博客文章就更难受了，而且几乎没有鲁棒性可言。

因此这里安装一个插件，通过一些方式为每篇文章生成短链接，只要不改变 footer-matter 的 id 值，则文章链接就不会变化。

1
2
3
4
5
## 安装插件
npm install hexo-abbrlink --save

## 修改 config 文件的 permalink 项
permalink: posts/:abbrlink.html  ## 此处可以自己设置

再在 config 文件下增加以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
## abbrlink config
abbrlink:
  alg: crc32      #support crc16(default) and crc32
  rep: hex        #support dec(default) and hex
  drafts: false   #(true)Process draft,(false)Do not process draft. false(default)
  ## Generate categories from directory-tree
  ## depth: the max_depth of directory-tree you want to generate, should > 0
  auto_category:
    enable: true  #true(default)
    depth:        #3(default)
    over_write: false
  auto_title: false #enable auto title, it can auto fill the title by path
  auto_date: false #enable auto date, it can auto fill the date by time today
  force: false #enable force mode,in this mode, the plugin will ignore the cache, and calc the abbrlink for every post even it already had abbrlink.

最后每篇文章对应的的链接就很短了。

配置 Front-matter

参考 Jerry 的文章 Butterfly 安装文档 (二) 主题页面

Front-matter 是 markdown 文件最上方以 — 分隔的区域，用于指定个别档案的变数。

  • Page Front-matter 用于页面配置，如 /_posts/about, /_posts/categories 等页面
  • Post Front-matter 用于文章页配置，就是具体的博文。

如何一劳永逸搞定 Front-matter

在网站本地根目录下面找到 scaffolds 文件夹，下有 page.md, post.md，按照下面的指示和配置文件修改即可。

本站使用 mathjax 渲染，因此 katex 不做设置，复制时还请注意。

Page Front-matter

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
---
title: {{title}}
date: {{date}}
type:
updated:
comments:
description:
keywords:
top_img:
mathjax: false
katex:
aside:
aplayer:
highlight_shrink:
random:
---
栏目 是否必要？ 解释
title yes 标题
date yes 创建日期
type yes 标签，分类，友链必须配置
updated no 页面更新日期
comments no 评论模块，默认 true
description no 页面描述
keywords no 页面关键词，用于链接 index 和 category?
top_img no 页面顶部图片
mathjax no 使用 mathjax 渲染公式，仅当 config 中 mathjax.per_page:false 时才需要按需配置，默认 false
katex no 使用 katex 渲染公式，仅当 config 中 katex.per_page:false 时才需要按需配置，默认 false
aside no 显示侧边栏，默认 true
aplayer no 在需要的页面加载 aplayer 的 js 和 css
highlight_shrink no 配置代码框是否展开，默认为 config 中 highlight_shrink 的配置
random no 友情链接是否随机排序，默认 false

Post Front-matter

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
---
title: {{title}}
date: {{date}}
updated:
tags:
categories:
keywords:
description:
top_img: true
comments:
cover:
toc:
toc_number:
toc_style_simple:
copyright:
copyright_author:
copyright_author_href:
copyright_url:
copyright_info:
mathjax: false
katex:
aplayer:
highlight_shrink:
aside:
abcjs:
---
栏目 是否必要？ 解释
title yes 标题
date yes 创建日期
updated no 更新日期
tags no 文章标签
categories no 文章分类
keywords no 文章关键词
description no 文章描述
top_img no 文章顶部图片
comments no 评论模块，默认 true
cover no 文章缩略图，若未设置 top_img 则文章顶部显示缩略图，可设为 false / 图片地址 / 留空
toc no 显示文章目录，默认为设置中的 toc.enable 设置
toc_number no 显示 toc_number，默认为设置中 toc.number 设置
toc_style_simple no 显示目录简洁模式
copyright no 显示文章版权模块，默认为设置中 post_copyright.enable 设置
copyright_author no 版权模块的 作者
copyright_author_href no 版权模块的 作者链接
copyright_url no 版权模块的 文章链接
copyright_info no 版权模块的 版权声明
mathjax no 使用 mathjax 渲染公式，仅当 config 中 mathjax.per_page:false 时才需要按需配置，默认 false
katex no 使用 katex 渲染公式，仅当 config 中 katex.per_page:false 时才需要按需配置，默认 false
aplayer no 在需要的页面加载 aplayer 的 js 和 css
highlight_shrink no 配置代码框是否展开，默认为 config 中 highlight_shrink 的配置
aside no 显示侧边栏，默认 true
abcjs no 加载 abcjs，仅当设置中 abcjs.perpage:false 时才需要按需配置，默认 false

主题配置（施工中）

参考竹山一叶的 Hexo 博客 Butterfly 主题配置

导航栏

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
  友链: /link/ || fas fa-link
  关于: /about/ || fas fa-heart
  清单 ||fas fa-list:
    - 音乐 || /music/ || fas fa-music
    - 电影 || /movies/ || fas fa-video
    - 照片 || /Gallery/ || fas fa-images

标签页,分类页

标签页配置

1
hexo new page tags

打开刚才的指令生成的 source/tag/index.md 文件，并按下面格式修改

1
2
3
4
5
6
7
---
title: 标签 ## 也可以直接写成 “tags”
date: 2024-04-13 17:02:11
type: "tags"
orderby: name ## random/name/length
order: 1 ## 1/-1 for ascending/descending
---

类似地，分类页配置

1
hexo new page categories

打开 source/categories/index.md，并按下面格式修改：

1
2
3
4
5
---
title: 分类
date: 2024-04-13 17:07:58
type: "categories"
---

新建其他页面

以新建一个笔记页Notes为例
在config_butterfly的menu部分新增：

1
- 笔记 || /notes/ || iconfont icon-5

图标替换见“网站更换图标库到Iconfont”。
然后新建notes文件夹

1
hexo new page notes

Hexo会使用 scaffolds/page.md生成一个文件夹 notes，和配套静态文件 index.md。
修改index.md中的Front-matter 中的type: “notes”

网站图标和头像

1
2
3
4
5
6
7
8
9
10
11
12
# Image
# Favicon
## All of these pictures should place in ./themes/butterfly/source/img
favicon: /img/favicon.png
# Avatar
avatar:
  img: /img/avatar.png
  effect: false
# The banner image of home page
index_img: /img/img.jpg
#background image
background: /img/bg.jpg

社交图标

修改themes/butterfly/_config.yml：（不知道只修改butterfly是否可以）

1
2
3
4
5
6
7
# Social Settings (社交圖標設置)
# formal:
#   icon: link || the description || color
social:
  fab fa-github: https://github.com/CMander02 || Github || '#24292e'
  # fas fa-envelope: mailto:[email protected] || Email || '#4a7dbe'
  fab fa-bilibili: https://space.bilibili.com/396895143 || BiliBili || '#fb7299'

网站更换图标库到Iconfont

参考Jerry的Butterfly进阶教程

Butterfly默认使用FontAwesome的免费图标。这个网站提供很多免费的矢量图标，但是总量和丰富程度有限，部分情况下需要更换其他图标。这里介绍一个使用阿里巴巴的iconfont站点的免费矢量图的流程。

  1. 首先去iconfont注册一个账号，然后按需搜索需要的图标。鼠标悬停在图标上点击购物车，将图标加入购物车。然后点击页面右上购物车图标，点击“添加至项目”，在“加入项目”的框右上角有一个文件夹按钮，点击之新建一个项目。
  2. 添加完项目后，网站会自动跳转到项目详情页面，点击“项目设置”——“暂无代码，点击生成”，网站生成css链接，复制之；
  3. 打开themes/butterfly/_config.yml，找到Inject配置，按要求添加刚才的css链接：
1
2
3
4
5
6
7
8
9
# Inject
# Insert the code to head (before '</head>' tag) and the bottom (before '</body>' tag)
# 插入代码到头部 </head> 之前 和 底部 </body> 之前
inject:
  head:
    - <link rel="stylesheet" href="//[这一段替换刚才复制的css链接]">
    # - <link rel="stylesheet" href="/xxx.css">
  bottom:
    # - <script src="xxxx"></script>
  1. 回到默认的config.butterfly.yml，找到menu设置，按需更改。图标使用格式为 iconfont [图标名]，其中图标名在网站的项目详情页，鼠标悬浮在图标上即可复制。

字数统计（有误）

1
2
3
4
5
6
7
8
9
10
11
12
post_meta:
  page: # Home Page
    date_type: both # created or updated or both 主頁文章日期是創建日或者更新日或都顯示
    date_format: date # date/relative 顯示日期還是相對日期
    categories: true # true or false 主頁是否顯示分類
    tags: true # true or false 主頁是否顯示標籤
    label: true # true or false 顯示描述性文字
    # add
    # 首页是否开启字数统计
    wordcount_enable: true
    # 首页是否显示开启阅读数量
    page_pv: true

代码渲染主题更改和代码框展开

在themes/butterfly/_config.yml 中修改，在_config.butterfly新增，默认为light

1
highlight_theme: darker #  darker / pale night / light / ocean / mac / mac light / false

代码框展开，复制一下内容至_config.butterfly.yml：

1
highlight_height_limit: 300 # unit: px

Hexo 使用 Mathjax引擎渲染数学公式

参考了Hexo渲染数学公式一文

更换渲染引擎

1
2
3
4
# 卸载原来的
npm uninstall hexo-renderer-marked --save
# 安装新的
npm install hexo-renderer-kramed --save

配置引擎

1
cd [root_file]/node_modules/kramed/lib/rules/inline.js

更改原本的11行和20行

1
2
3
4
//11    escape: /^\\([\\`*{}\[\]()#$+\-.!_>])/,
escape: /^\\([`*\[\]()#$+\-.!_>])/,
//20    em: /^\b_((?:__|[\s\S])+?)_\b|^\*((?:\*\*|[\s\S])+?)\*(?!\*)/,
    em: /^\*((?:\*\*|[\s\S])+?)\*(?!\*)/,

在主题中开启Mathjax

config文件中新增：

1
2
3
4
# MathJax Support
mathjax:
  enable: true
  per_page: false ##不需要每页都开，需要的时候在post的header打开即可，默认关闭以加速网页

在文章中使用Mathjax

1
2
3
4
5
6
---
title: xxx
date: 2016-12-28 21:01:30
tags:
mathjax: true ##需要用的文章在Post header中把这个设置为true，前面默认设置为false
---

Hexo 配置本地搜索

参考Butterfly主题添加本地搜索功能

安装搜索引擎

1
npm install hexo-generator-search --save

_config.butterfly.yml 新增

1
2
3
4
5
6
7
8
9
10
# Local search
local_search:
  enable: true
  # Preload the search data when the page loads.
  preload: false
  # Show top n results per article, show all results by setting to -1
  top_n_per_article: 1
  # Unescape html strings to the readable one.
  unescape: false
  CDN:

_config.yml 新增

1
2
3
4
5
6
# 添加本地搜索
search:
  path: search.xml
  field: post
  content: true
  format: html

Hexo 引入访问者地图

参考添加访客地图
注意，本地图是按照ip地址定位的

从第三方网站获取地图代码

在clustrmaps官网注册账号，在下面找到website widget，输入 Github Pages 网址，点击 Get Map Widget。

网站提供平面地图 Map Widget 和 球形地图 Globe Widget，这里选择球形地图。

点击 Select，就创建好了。之后只需要复制到博客就行。

引入至 Hexo

  1. 在themes\butterfly\layout\includes\widget中新建card_map.pug文件
1
2
3
4
5
6
.card-widget.card-map
  .card-content
    .item-headline
      i.fa.fa-globe-asia(aria-hidden="true")
      span= _p('aside.card_map')
    script#clstr_globe(type="text/javascript" defer="defer" src="这里填写你从clustrmap中复制的代码中的src")
  1. 修改themes\butterfly\layout\includes\widget\index.pug 文件，在需要的位置插入下面的代码
1
!=partial('includes/widget/card_map', {}, {cache: true})
  1. 在themes\butterfly\_config.yml中找到 card_webinfo 下面添加一行card_map: true

Hexo插入少量图片

参考Hexo不显示图片,不需要插件,超简单

对于不同位置的图片，建议使用不同方法（一般来说是图床）存放和引用。

文章内图片：安装特定依赖，不同文件夹分别存放

config 和config.butterfly修改：

1
2
# post_asset_folder: false
post_asset_folder: true

然后安装依赖 hexo-asset-image

1
npm install hexo-asset-image --save

此时重新在命令行执行hexo n "blabla"的时候，会在_posts下面生成一个同名文件夹。图片放在里面即可，引用时按照下面的语法即可

1
![图片名](文件夹名/图片名.后缀)

文章头图：直接丢到source下面

在source下面新建一个专门存放图片的文件夹，比如pic。将图片存放进去，然后如下正常使用markdown语法引用即可。注意一定是/pic起手，不要丢斜杠。

1
![img](/pic/xxx.png)

添加RSS

本文参考面具熊小屋的文章 Hexo butterfly 主题添加 RSS 插件
首先安装插件

1
npm install hexo-generator-feed --save

配置根目录_config.butterfly.yml，新增如下内容

1
2
3
4
5
6
7
8
9
10
11
12
13
feed:
  enable: true #是否启用插件
  type: atom #有atom和rss2两个选项，使用默认atom就好了
  path: atom.xml #也用默认配置atom.xml就行
  limit: 20 #展示文章的数量,使用 0 或 false 代表展示全部
  hub: #这个我没用上，根据官网，空着就行
  content: #默认是false，true的话会在rss文件中包含整个文章内容
  content_limit: 140 #摘要长度
  content_limit_delim: ' ' #没看明白官方的意思，就跟着默认不填了
  order_by: -date #采用日期进行排序
  icon: icon.png #给rss链接配置icon
  autodiscovery: true #自动发现提要
  template: #给rss文章配置模板

配置themes\butterfly\_config.yml，新增

1
rss: /atom.xml

并在social setting下新增内容

1
fas fa-rss: https://https://[Blog URL]//atom.xml || RSS || '#eb6c22'

文章显示自定义简介

在_config.butterfly.yml中新增

1
2
3
4
5
6
7
8
# Display the article introduction on homepage
# 1: description
# 2: both (if the description exists, it will show description, or show the auto_excerpt)
# 3: auto_excerpt (default)
# false: do not show the article introduction
index_post_content:
  method: 2
  length: 500 # if you set method to 2 or 3, the length need to config

三种简介策略分别是：

  1. 按照front matter内容，没有则置空
  2. 按照front matter中description内容，没有则自动提取文章开头length个字符
  3. （默认）提取文章开头length个字符

Hexo配置更好的Markdown渲染器（部分无效）

参考了【Hexo】选择更高级的Markdown渲染器

安装

卸载 hexo-renderer-marked，安装hexo-renderer-markdown-it

1
2
npm un hexo-renderer-marked --save
npm i hexo-renderer-markdown-it --save

配置

复制下面内容到_config.butterfly.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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
markdown:
  preset: "default"
  render:
    html: true
    xhtmlOut: false
    langPrefix: "language-"
    breaks: true
    linkify: true
    typographer: true
    quotes: "“”‘’"
  enable_rules:
  disable_rules:
  plugins:
    - markdown-it-abbr
    - markdown-it-cjk-breaks
    - markdown-it-deflist
    - markdown-it-emoji
    - markdown-it-footnote
    - markdown-it-ins
    - markdown-it-mark
    - markdown-it-sub
    - markdown-it-sup
    - markdown-it-checkbox
    - markdown-it-imsize
    - markdown-it-expandable
    - name: markdown-it-container
      options: success
    - name: markdown-it-container
      options: tips
    - name: markdown-it-container
      options: warning
    - name: markdown-it-container
      options: danger
  anchors:
    level: 2
    collisionSuffix: ""
    permalink: false
    permalinkClass: "header-anchor"
    permalinkSide: "left"
    permalinkSymbol: "¶"
    case: 0
    separator: "-"

再安装下面三个插件：

1
2
3
npm i markdown-it-checkbox
npm i markdown-it-imsize
npm i markdown-it-expandable

施工中…