hexo折腾笔记

发表于 更新于 本文字数： 8k 阅读时长 ≈ 7 分钟

生命不息，折腾不止！

注：本文大部分内容写于2018年，使用的Hexo版本为3.x，NexT版本为v5，部分内容已过时，当前（2021年），Hexo版本已升级到5.x，NexT主题版本已更新到v8，最新的配置参见Hexo和NexT的官方文档。

搭建环境

1、安装 Node.js Node.js 官网
建议下载 LTS 版本，官网首页的 LTS 是14.x版本，如果使用Windows 7操作系统，则需要下载12.x版本

2、安装 Git 官网下载 清华镜像

3、安装 Hexo

1
npm install hexo-cli -g

注：nodejs 和 npm 的仓库托管在 S3 上，在国内访问十分困难，这里可以用淘宝的镜像站 npm.taobao.org 代替。

npm 使用 registry 这个属性指定仓库，因此配置这个属性即可。修改 npm 配置属性的几种方法详见官方文档。

修改 registry 的方法，以下三种任意一种即可:

  1. 修改~/.npmrc文件(没有就自行新建一个)，写入
    registry = https://registry.npm.taobao.org
  2. 添加环境变量NPM_CONFIG_REGISTRY=https://registry.npm.taobao.org
  3. 使用命令npm config set registry https://registry.npm.taobao.org

类似地，以下命令将disturl属性指向 https://npm.taobao.org/dist
npm config set disturl https://npm.taobao.org/dist

初始化博客

新建并进入博客文件夹blog(在运行以下命令前，确保此文件夹是空文件夹)，在此处打开Git Bash，输入

1
hexo init

配置博客

在blog目录下，用文本编辑器打开_config.yml（站点配置文件），修改参数。

注意，在每个参数的:后都需要有一个空格

修改网站相关信息

1
2
3
4
5
6
7
8
# Site
title: 水木风的个人博客
subtitle:
description:
keywords:
author: dslwind
language: zh-CN
timezone: Asia/Shanghai

配置 URL

将url修改为个人域名、github.io等的网址。

例如：

1
url: dslwind.github.io

对于root（根目录）、permalink（永久链接）、permalink_defaults（默认永久链接）等其他信息保持默认。

配置部署

1
2
3
4
deploy:
  type: git
  repo: https://github.com/dslwind/dslwind.github.io.git
  branch: master

此外，可将_config.yml中的repo修改为如下标准格式：

1
repo: https://用户名:密码@github.com/用户名/用户名.github.io.git

这样做的好处就是每次hexo deploy提交时不需要输入账号密码。

发表文章

新建博文

在命令行中输入:

1
hexo new "测试文章"

编辑博文

上述命令会在source/_posts/文件夹生成测试文章.md的markdown文件，打开并编辑该文件。

在文件开头处，可以按如下格式添加文章标题，日期，分类、标签以及描述等。

1
2
3
4
5
6
7
8
9
---
title: 测试文章 # 文章标题
date: 2018-08-25 15:33:11 # 文章生成时间
categories:               # 文章分类目录(具有层次性) 可以省略
    - "Hexo教程"
    - "子分类"
tags: [tag1, tag2]        # 文章标签 可以省略
 description:             # 你对本页的描述 可以省略
---

生成页面

运行以下命令

1
2
3
4
5
6
7
8
9
10
11
12
13
$ hexo clean
INFO  Deleted database.
INFO  Deleted public folder.

$ hexo generate
INFO  Start processing
INFO  Files loaded in 1.48 s
...
INFO  29 files generated in 4.27 s

$ hexo server
INFO  Start processing
INFO  Hexo is running at http://localhost:4000/. Press Ctrl+C to stop.

打开http://localhost:4000/，可以在本地预览网站的初步样子。

发布博文

执行hexo deploy

1
2
3
4
5
$ hexo deploy
INFO  Deploying: git
INFO  Clearing .deploy_git folder...
INFO  Copying files from public folder...
...

执行hexo deploy时如果出现错误

1
deploy not found: git

则执行如下语句后，再部署即可：

1
npm install hexo-deployer-git --save

总结

发布文章的步骤：

1、hexo new 创建文章(当然也可以通过其他方式创建 Markdown 文件)

2、Markdown 语法编辑文章

3、部署

1
2
3
4
hexo clean    # 清除缓存 网页正常情况下可以忽略此条命令
hexo generate # 生成
hexo server   # 启动服务预览，非必要，可本地浏览网页
hexo deploy   # 部署发布

其中的部分命令可以简写：

1
2
3
4
hexo n "我的博客" == hexo new "我的博客" # 新建文章
hexo g == hexo generate                 # 生成
hexo s == hexo server                   # 启动服务预览
hexo d == hexo deploy                   # 部署

安装并使用 NexT 主题

在blog目录下运行：

1
git clone https://github.com/theme-next/hexo-theme-next themes/next

修改站点配置文件_config.yml

1
theme: next

更新 NexT 主题：

1
2
cd themes/next
git pull

设置 NexT 主题模式

在 NexT 主题中，有四种不同的模式，通过切换模式，NexT 主题显示不一样的样式。

在 NexT 根目录下有一个同样名称为_config.yml，将其称为主题配置文件，在其中找到scheme属性，如下所示：

1
2
3
4
5
# Schemes
#scheme: Muse
#scheme: Mist
#scheme: Pisces
scheme: Gemini

NexT 主题默认使用 Muse 模式，可根据自己的喜好，选择其中一种模式，本博客采用 Gemini 模式。

NexT 主题已原生支持暗黑模式，以下设置可以启用暗黑模式

1
2
# Dark Mode
darkmode: true

设置预览摘要

设置完模式后，尽管首页显示的是所有文章的列表，但是每一篇文章都显示了所有内容，这样感觉看起来不舒服，这时候可以启用预览摘要模式，在主题配置文件中找到excerpt_description属性，设置为true：

1
excerpt_description: true #将原有的false改为true

另一种方案是在写md文件的时候，手动插入<!-- more -->标记，这样做的好处是可以精确设置需要预览的文字。

添加菜单选项

默认情况下，菜单导航栏有首页和归档两个选项，可根据需要添加分类、标签和关于等。在主题配置文件中，找到menu属性，并去掉categories、 tags、about的注释，如下所示：

1
2
3
4
5
6
7
8
9
menu:
  home: / || fa fa-home
  about: /about/ || fa fa-user
  tags: /tags/ || fa fa-tags
  categories: /categories/ || fa fa-th
  archives: /archives/ || fa fa-archive
  #schedule: /schedule/ || fa fa-calendar
  #sitemap: /sitemap.xml || fa fa-sitemap
  #commonweal: /404/ || fa fa-heartbeat

调整属性的顺序将直接影响页面菜单显示的次序。

然后在博客根目录执行如下命令，添加相应页面：

1
2
3
4
hexo new page "categories"
hexo new page "tags"
hexo new page "about"
hexo new page "archives"

执行完上述指令后，博客根目录的source文件夹下会创建三个文件夹categories、tags、about和archives，这些文件夹中各有一个index.md文件，

修改这四个 Markdown 文件内容，分别添加对应的type属性，例如：

1
2
3
4
5
6
---
title: categories
date: 2018-01-01 08:00:00
type: "categories"
---

完成文件的修改，然后部署 Hexo 即可完成菜单选项的添加。

渲染数学公式

在主题配置文件中，定位到 mathjax，将enable选项设置为 true。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# Math Formulas Render Support
math:
  # Default (true) will load mathjax / katex script on demand.
  # That is it only render those page which has `mathjax: true` in Front-matter.
  # If you set it to false, it will load mathjax / katex srcipt EVERY PAGE.
  per_page: true

  # hexo-renderer-pandoc (or hexo-renderer-kramed) required for full MathJax support.
  mathjax:
    enable: true
    # See: https://mhchem.github.io/MathJax-mhchem/
    mhchem: false

  # hexo-renderer-markdown-it-plus (or hexo-renderer-markdown-it with markdown-it-katex plugin) required for full Katex support.
  katex:
    enable: false
    # See: https://github.com/KaTeX/KaTeX/tree/master/contrib/copy-tex
    copy_tex: false

根据上面的注释说明，须在需要渲染数学公式的页面中加入mathjax: true，这样做的好处是，可以根据需要加载 mathjax 脚本；如果将per_page设置为false，则所有页面都会加载mathjax。
更多关于数学公式的显示，参见 NexT 主题文档

修改页脚

修改主题配置文件，定位到footer，修改属性如下

1
2
3
4
footer:
  # Specify the date when the site was setup.
  # If not defined, current year will be used.
  since: 2018 #自定义博客起始年份

修改文章底部的#号标签

在主题配置文件中，定位到tag_icon，将其属性修改为true：

1
2
# Use icon instead of the symbol # to indicate the tag at the bottom of the post
tag_icon: true

添加加载进度条

在主题配置文件中，定位到pace，将enable选项设置为 true，并使用 CDN 加载

1
2
3
4
5
6
7
8
9
10
11
pace:
  enable: true
  # Themes list:
  # big-counter | bounce | barber-shop | center-atom | center-circle | center-radar | center-simple
  # corner-indicator | fill-left | flat-top | flash | loading-bar | mac-osx | material | minimal
  theme: center

vendors:
  ...
  pace: //cdn.jsdelivr.net/npm/pace-js@1/pace.min.js
  pace_css: //cdn.jsdelivr.net/npm/pace-js@1/themes/black/pace-theme-center-atom.css

添加阅读进度条

在主题配置文件中，定位到reading_progress，将enable选项设置为 true：

1
2
3
4
5
6
7
# Reading progress bar
reading_progress:
  enable: true
  # Available values: top | bottom
  position: top
  color: "#37c6c0"
  height: 3px

添加返回顶部按钮

在主题配置文件中，定位到back2top，将enable选项设置为 true：

1
2
3
4
5
6
back2top:
  enable: true #启用按钮
  # Back to top in sidebar.
  sidebar: false
  # Scroll percent label in b2t button.
  scrollpercent: true #在按钮上显示百分比

修改代码高亮配色并启用代码段复制按钮

修改主题配置文件codeblock字段

1
2
3
4
5
6
7
8
9
10
11
12
codeblock:
  # Code Highlight theme
  # Available values: normal | night | night eighties | night blue | night bright | solarized | solarized dark | galactic
  # See: https://github.com/chriskempson/tomorrow-theme
  highlight_theme: night
  # Add copy button on codeblock
  copy_button:
    enable: true
    # Show text copy result.
    show_result: true
    # Available values: default | flat | mac
    style:

页面右上角添加 GitHub 按钮

在主题配置文件中，定位到github_banner，将enable选项设置为 true，并修改permalink指向：

1
2
3
4
5
# `Follow me on GitHub` banner in the top-right corner.
github_banner:
  enable: true
  permalink: https://github.com/dslwind
  title: Follow me on GitHub

行内代码样式自定义

打开themes/next/source/css/_common/components/post/post.styl，在.post-body里加入

1
2
3
4
code {
  color: #ff7600;
  background: none;
}

颜色可以自己定义，注意将backgroud设置为none，否则暗黑模式下背景色会瞎眼。

设置个人头像

在主题配置文件中，定位到avatar属性，

1
2
3
4
5
6
7
8
9
10
11
12
# Sidebar Avatar
avatar:
  # in theme directory(source/images): /images/avatar.gif
  # in site  directory(source/uploads): /uploads/avatar.gif
  # You can also use other linking images.
  url: https://tvax2.sinaimg.cn/large/7fa1e0d7ly1ff52f888f4j20md0mbwh0.jpg
  # If true, the avatar would be dispalyed in circle.
  rounded: true
  # The value of opacity should be choose from 0 to 1 to set the opacity of the avatar.
  opacity: 1
  # If true, the avatar would be rotated with the cursor.
  rotated: true

项目主页添加 README

如果直接使用命令hexo n README，再部署至远程的时候，hexo 会将它解析为 html 文件；此外，如果手动在远程仓库添加Readme文件，hexo 每次部署时也会删掉该文件。

解决方式是在source目录下手动新建一个README.mdown文件（注意这里的后缀是.mdown），或者新建一个Readme.txt文件。然后再在这个新建文件中写 README 即可。再之后hexo g会把它复制到public文件夹，而不会解析成html文件，发布在博客中。

添加字数统计和阅读时长

首先安装插件

1
npm install hexo-symbols-count-time --save

修改站点配置文件中添加如下代码即可开启统计功能：

1
2
3
4
5
symbols_count_time:
  symbols: true
  time: true
  total_symbols: true
  total_time: true

修正图片显示问题

默认配置时，博客文章里面的本地图片不会同步上传。解决方案如下：

1、把站点配置文件里的post_asset_folder选项设置为true

2、安装图片上传插件

1
npm install hexo-asset-image --save

3、插件安装完成后，再运行hexo n "xxxx"来生成博文时source/_posts文件夹内除了xxxx.md文件外，还将生成一个名为xxxx的文件夹

4、在xxxx.md中引入图片时，先把图片复制到xxxx文件夹，然后按如下格式引入图片：

1
![你想输入的替代文字](xxxx/图片名.jpg)

添加社交链接

修改主题设置文件的social属性

1
2
3
4
5
6
7
8
9
10
11
social:
  GitHub: https://github.com/dslwind || fab fa-github
  #E-Mail: mailto:yourname@gmail.com || fa fa-envelope
  #Weibo: https://weibo.com/yourname || fab fa-weibo
  #Google: https://plus.google.com/yourname || fab fa-google
  #Twitter: https://twitter.com/yourname || fab fa-twitter
  #FB Page: https://www.facebook.com/yourname || fab fa-facebook
  #StackOverflow: https://stackoverflow.com/yourname || fab fa-stack-overflow
  #YouTube: https://youtube.com/yourname || fab fa-youtube
  #Instagram: https://instagram.com/yourname || fab fa-instagram
  #Skype: skype:yourname?call|chat || fab fa-skype

参考资料