预计阅读时长：15min
全文字数：4000+
前置知识：已注册Github账号，已安装配置好Git，已安装Node.js
0 前言
教程分为三个部分：
hexo的初级搭建及部署到github page上hexo的基本配置，更换主题主题拓展功能的实现，包括站内搜索、阅读量统计、评论系统等
1 搭建
- 安装
Git - 安装
Node.js - 安装
Hexo GitHub创建个人仓库- 生成
SSH添加到GitHub - 将
hexo部署到GitHub - 设置个人域名
- 发布文章
1.1 安装Git
Git是目前世界上最先进的分布式版本控制系统，可以有效、高速的处理从很小到非常大的项目版本管理。学习使用Git是每个程序猿的必经之路，可以学习黑马程序员Git教程。
不确定是否已安装配置好，可通过在cmd中输入git -v来查看一下版本，验证是否安装成功。
1.2 安装Node.js
Hexo是基于node.js编写的，所以需要安装一下node.js和里面的npm工具。
下载稳定版或者最新版都可以Node.js，安装选项全部默认，一路点击Next。
最后安装好之后，按Win+R打开命令提示符，输入node -v和npm -v，如果出现版本号，那么就安装成功了。
1.3 安装Hexo
前面git和nodejs安装好后，就可以安装hexo了，您可以先创建一个文件夹MyBlog，用来存放自己的博客文件，然后cd到这个文件夹下（或者在这个文件夹下直接右键git bash打开）。
比如我的博客文件都存放在D:\Study\MyBlog目录下。
在该目录下右键点击Git Bash Here，打开git的控制台窗口，以后我们所有的操作都在git控制台进行，就不用Windows自带的cmd了。
定位到该目录下，输入npm install -g hexo-cli安装Hexo。可能会有几个报错，无视它就行。
1 | npm install -g hexo-cli |
安装完后输入hexo -v验证是否安装成功。
至此hexo就安装完了。
接下来初始化一下hexo,即初始化我们的网站，进入我们主题根目录Hexo，输入hexo init初始化文件夹
1 | hexo init |
这个Hexo可以自己取什么名字都行，然后，接着输入npm install安装必备的组件。
新建完成后，指定文件夹Hexo目录下有：
node_modules:依赖包public：存放生成的页面scaffolds：生成文章的一些模板source：用来存放您的文章themes：主题**_config.yml:博客的配置文件**
这样本地的网站配置也弄好啦，输入hexo g生成静态网页，然后输入hexo s打开本地服务器，
1 | hexo g |
按ctrl+c关闭本地服务器。
1.4 注册Github账号，创建个人仓库
默认您已经完成注册。
打开Github，新建一个项目仓库New repository，如下所示：
要创建一个和您用户名相同的仓库，后面加
.github.io。只有这样，将来要部署到GitHub page的时候，才会被识别，也就是 http://xxxx.github.io ，其中xxx就是您注册GitHub的用户名。例如我的：YuLinzhong的个人主页
1.5 生成SSH添加到GitHub
这一步通常和1.1 安装Git一起完成，这里默认您已经完成。
1.6 将hexo部署到GitHub
这一步，我们就可以将hexo和GitHub关联起来，也就是将hexo生成的文章部署到GitHub上，打开博客根目录下的_config.yml文件，这是博客的配置文件，在这里您可以修改与博客配置相关的各种信息。
修改最后一行的配置：
1 | deploy: |
repository修改为您自己的github项目地址，即部署时，告诉工具，将生成网页通过git方式上传到您对应的链接仓库中。
这个时候需要先安装deploy-git ，也就是部署的命令,这样您才能用命令部署到GitHub。
1 | npm install hexo-deployer-git --save |
然后
1 | hexo clean |
其中 hexo clean清除了您之前生成的东西，也可以不加。 hexo generate顾名思义，生成静态文章，可以用 hexo g缩写 ，hexo deploy部署文章，可以用hexo d缩写。
注意
deploy时可能要您输入username和password。
稍等片刻，您就可以在自己的网站 http://yourname.github.io/ 看到博客了。
1.7 设置个人域名
这一步选择性完成，因为个人暂时不是很需要，所以这里先跳过。
1.8 写文章、发文章
首先在博客根目录下右键打开git bash，安装一个扩展npm i hexo-deployer-git。
然后输入hexo new post "我的第一篇博客"，新建一篇文章。
然后打开D:\Hexo\source\_posts的目录，可以发现下面多了一个文件夹和一个.md文件，一个用来存放您的图片等数据，另一个就是您的文章文件啦。
您可以会直接在vscode里面编写markdown文件，可以实时预览，也可以用用其他编辑md文件的软件的工具编写。
编写完markdown文件后，根目录下输入hexo g生成静态网页，然后输入hexo s可以本地预览效果，最后输入hexo d上传到github上。这时打开您的github.io主页就能看到发布的文章啦。
到这儿基本第一部分就完成了，已经完整搭建起一个比较简陋的个人博客了，接下来我们就可以对我们的博客进行个性化定制了。
2 定制主题
2.1 Hexo相关目录文件
2.1.1 博客目录构成介绍
我们博客的目录结构如下：
1 | - node_modules |
node_modules是node.js各种库的目录，public是生成的网页文件目录，scaffolds里面就三个文件，存储着新文章和新页面的初始设置，source是我们最常用到的一个目录，里面存放着文章、各类页面、图像等文件，themes存放着主题文件，一般也用不到。
我们平时写文章只需要关注source/_posts和public/img就行了。
2.1.2 hexo基本配置
在文件根目录下的_config.yml，就是整个hexo框架的配置文件了。可以在里面修改大部分的配置。详细可参考官方的配置描述。
| 参数 | 描述 |
|---|---|
title |
网站标题 |
subtitle |
网站副标题 |
description |
网站描述 |
keywords |
网站的关键词。支持多个关键词。 |
author |
您的名字 |
language |
网站使用的语言。对于简体中文用户来说，使用不同的主题可能需要设置成不同的值，请参考您的主题的文档自行设置，常见的有 zh-Hans和 zh-CN。 |
timezone |
网站时区。Hexo 默认使用您电脑的时区。请参考 时区列表 进行设置，如 America/New_York, Japan, 和 UTC 。一般的，对于中国大陆地区可以使用 Asia/Shanghai。 |
2.1.2.1 网站
| 参数 | 描述 |
|---|---|
title |
网站标题 |
subtitle |
网站副标题 |
description |
网站描述 |
keywords |
网站的关键词。支持多个关键词。 |
author |
您的名字 |
language |
网站使用的语言。对于简体中文用户来说，使用不同的主题可能需要设置成不同的值，请参考您的主题的文档自行设置，常见的有 zh-Hans和 zh-CN。 |
timezone |
网站时区。Hexo 默认使用您电脑的时区。请参考 时区列表 进行设置，如 America/New_York, Japan, 和 UTC 。一般的，对于中国大陆地区可以使用 Asia/Shanghai。 |
其中，description主要用于SEO，告诉搜索引擎一个关于您站点的简单描述，通常建议在其中包含您网站的关键词。author参数用于主题显示文章的作者。
2.1.2.2 网址
| 参数 | 描述 | 默认值 |
|---|---|---|
url |
网址, 必须以 http:// 或 https:// 开头 |
|
root |
网站根目录 | url's pathname |
permalink |
文章的 永久链接 格式 | :year/:month/:day/:title/ |
permalink_defaults |
永久链接中各部分的默认值 | |
pretty_urls |
改写 permalink 的值来美化 URL |
|
pretty_urls.trailing_index |
是否在永久链接中保留尾部的 index.html，设置为 false 时去除 |
true |
pretty_urls.trailing_html |
是否在永久链接中保留尾部的 .html, 设置为 false 时去除 (对尾部的 index.html无效) |
true |
在这里，您需要把url改成您的网站域名。
permalink，也就是您生成某个文章时的那个链接格式。比如我新建一个文章叫temp.md，那么这个时候他自动生成的地址就是http://yoursite.com/2022/05/08/temp。
因为默认格式是/年/月/日/题目，但个人觉得不够简洁，所以换成了/主题/题目。
1 | URL |
2.1.2.3 主题
1 | theme: landscap |
theme就是选择什么主题，也就是在themes这个文件夹下，在官网上有很多个主题，默认给你安装的是lanscape这个主题。当你需要更换主题时，在官网上下载，把主题的文件放在themes文件夹下，再修改这个主题参数就可以了。
2.1.2.4 Front-matter
Front-matter 是md文件最上方以 ---分隔的区域，用于指定个别文件的变量，官方[配置描述](Front-matter | Hexo)有详细介绍，下为示例。
1 | title: Github+Hexo+Annie博客搭建 |
-号和冒号后一定要有空格！
不同主题其Front-matter可能会有些许不同，因为本博客采用Annie主题，所以和官网的有出入。
2.1.2.5 layout（布局）
- post
当你每一次使用代码
1 | hexo new XXX |
它其实默认使用的是post这个布局，也就是在source文件夹下的_post里面。
Hexo有三种默认布局：post、page和draft，它们分别对应不同的路径，而您自定义的其他布局和post相同，都将储存到source/_posts文件夹。
而new这个命令其实是：
1 | hexo new [layout] <title> |
只不过这个layout默认是post罢了。
- page
如果你想另起一页，那么可以使用
1 | hexo new page newpage |
系统会自动给你在source文件夹下创建一个newpage文件夹，以及newpage文件夹中的index.md，这样你访问的newpage对应的链接就是 http://xxx.xxx/newpage
- draft
draft是草稿的意思，也就是你如果想写文章，又不希望被看到，那么可以
1 | hexo new draft newdraft |
这样会在source/_draft中新建一个newdraft.md文件，如果你的草稿文件写的过程中，想要预览一下，那么可以使用
1 | hexo server --draft |
在本地端口中开启服务预览。
如果你的草稿文件写完了，想要发表到post中，
1 | hexo publish draft newdraft |
就会自动把newdraft.md发送到post中。
2.2 更换主题
我们在了解Hexo博客文件基础之后，知道主题文件就放在themes文件下，那么我们就可以去Hexo官网下载喜欢的主题，复制进去然后修改参数即可。
个人比较喜欢的主题是 Annie ，您可以在 Themes | Hexo 自由选择自己喜欢的主题进行之后的配置。
Features
- 文艺、优雅、简洁的博客主题
- 页头随机背景+文章缩略图背景
- 两种主页模板，主页文章无限加载
- 分类页、标签页点击指定分类、标签后，查询并展示相关文章
- 相册页可以分类、搜索图片
- 相关文章模块：文章页展示与该篇文章相关的系列文章
- 文章评论模块：gitalk 、valine 、livere
- 文章分享模块：addThis 、baiduShare 、shareThis 、socialShare
- 文章统计模块：leancloud 、busuanzi
- 文章点赞模块：leancloud
- 文章阅读模块：toc目录、进度条、进度百分比
- 文章代码模块：代码复制、代码语言提示、5种高亮主题（Refer & use Next’ theme）
- 文章Markdown：支持数学公式(MathJax)，color quote(Refer & use Minos’ theme)
- 站点分析模块：baidu_analytics 、cnzz_analytics 、google_analytics 、tencent_analytics:
- 站点文章搜索：local search
- 多语言支持：中文简体、中文繁体、英文
在任意目录下使用git clone
1 | git clone https://github.com/Sariay/hexo-theme-Annie.git |
将站点目录下的_config.yml文件中的theme字段修改为Annie。
1 | # Extensions |
同时，将克隆得到的文件夹改名为Annie，放到themes目录下。
3 功能扩展
3.1 站点配置
原则上，你应该编辑站点目录下的_config.yml文件。
3.1.1 语言支持和时区更改
1 | # Site |
设置language的值：en | zh-CN |zh-TW
设置timezone的值：Asia/Shanghai，默认是以电脑时区为准。
3.1.2 站内搜索
第一步：安装 hexo-generator-search-zip插件
1 | $ npm install hexo-generator-search-zip --save |
第二步：编辑站点目录下的_config.yml文件
1 | # 添加下列参数 |
3.1.3 代码高亮
基于hexo自身的代码块解析插件的特性，弃用hexo-prism-plugin，参考、使用next主题的代码风格。
highlight、line_number的值应为true
1 | # Writing |
3.1.4 首页的分页
hexo博客默认首页分页，编辑站点配置文件，置参数per_page为1、2、3…..以达到分页目的，0则不分页。
1 | # Home page setting |
3.1.5 归档页的使用
Annie主题的归档页按年归档，不分页。当然，可以置参数archive_generator.per_page（站点配置文件）为1、2、3…..以达到分页目的。
warning!
Annie主题中无效，分页是对该页面[主页、归档页、标签页、分类页]的文章进行分页，即每次（每页）展示指定数量的文章
1 | archive: 1 |
3.1.6 分类页的使用
执行命令，创建分类页
1 | $ hexo new page categories |
然后编辑站点目录下的source/categories/index.md，添加如下Front-matter
1 | title: categories |
3.1.7 标签页的使用
执行命令，创建标签页
1 | $ hexo new page tags |
然后编辑站点目录下的source/tags/index.md，添加如下Front-matter
1 | title: tags |
3.1.8 关于页的使用
执行命令，创建关于页
1 | $ hexo new page about |
然后编辑站点目录下的source/about/index.md，添加如下Front-matter
1 | title: about |
3.1.9 相册页的使用
执行命令，创建相册页
1 | $ hexo new page gallery |
然后编辑站点目录下的source/gallery/index.md，添加如下Front-matter
1 | title: gallery |
打开文件data.json（Annie/source/plugin/gallerypage/data.json）, 按照json语法在数组[……]中添加gallery的图片数据，请设置合适的eWidth、eHeight的值。
warning!
注意：下列注释在json文件中无效，使用时请去掉注释。（注释仅为说明）
1 | [ |
当然，你可以将该文件data.json移至其他目录，相应地修改Annie\_config.yml中的gallery_data。
1 | # gallery page |
3.2 主题配置
功能拓展往往是站点目录下的_config.yml文件和主题目录下的_config.yml文件同时修改才能启用。
3.2.1 站内搜索
编辑主题目录下的_config.yml文件
1 | # 添加下列参数(若不存在)，并将enable置为true！ |
3.2.2 代码高亮
设置highlight_theme、code_copy（主题目录的config.yml）
1 | # post_code |
3.2.3 LOGO和FAVICON
编辑主题配置文件，设置favicon和logo的路径即可。当然，你可以使用文字logo或图片logo，即logo的值为空时，主题使用title的值作为logo！
1 | # favicon & logo |
3.2.4 页头背景图片
文章详情页的页头背景图片为该文章的封面图，其他页的页头背景图片为随机图片或固定图片。原则上，使用固定图片时，应将参数mode设为normal，然后设置normal_url的路径；使用随机图片时，应将参数mode设为random，然后设置random_url的路径。
warning!
注意跨域问题，尽量不使用跨域的图片（即背景图片和网页最好托管在一起，存放于同一服务器）
- 使用固定图片，请确保参数
mode设为normal，然后设置参数normal_url的值
1 | # background_image |
- 使用unplash随机图片，请确保参数
mode设为normal，然后设置参数normal_url的值
1 | # background_image |
- 使用自定义随机图片，请确保参数
mode设为random，然后设置参数random_max、random_url的值
- 第一步、fork 随机图片集 ；
- 第二步、开启你所fork的仓库的page服务；
- 第三步、获取相对地址；
- 第四步、设置
random_url为获得的相对地址。
1 | # background_image |
你可以将随机图片集上传到图床（腾讯云、七牛云等），然后获取https://....../Random-img/格式的地址，最后将random_url的值设置为该地址。
你也可以在主题目录下的img文件夹中新建Random-img文件夹，将0.jpg、1.jpg、2.jpg、3.jpg……110.jpg命名格式的图片放入其中，然后将random_url的值设置为/img/Random-img/。
warning!
图片的命名使用连续的整数，random_max的值小于等于（0、1、2、3…..110）的最大整数。（ps：如你偏爱访问速度🙃，尽可能使用固定图片）
3.2.5 随机名言与当地时间
每次刷新网页，网页页头展示一条随机名言，获取并展示该时区的标准时间。
1 | # motto |
在Annie\source\plugin\motto中保存了本地的motto。
时间设置暂时还有一定问题。
3.2.6 预加载遮罩
预加载遮罩的作用为，确保背景图片加载完成和背景构造完成。当背景加载并构造完成时，主题立即移除遮罩。预加载行为的超时时间默认设为10s，即最多10s左右后，不管背景是否加载并构造完成，主题都移除遮罩。你可以决定是否使用：
1 | # 02-PROLOADER |
3.2.7 首页的使用
首页文章展示有两种模式：图文模式cart和纯净模式pure。默认图文模式（cart），你只需编辑主题配置文件，设置index-style的参数，即可使用或扩展指定的主页文章展示模式。
1 | # 03-INDEX |
3.2.8 文章封面图
1 | title: Annie主题使用说明 |
cover参数值即为图片路径，路径可为相对路径或绝对路径。
博文的封面页要放在 themes/Annis/source/img 内，然后就可以用相对路径了。我这里放到了source/img/post-cover里，所以我的引用路径是/img/post-cover/cover001.jpg
3.2.9 文字的截断
1 | # post_excerpt for index page |
excerpt_cart为图文模式的截取字数，推荐小于等于100。excerpt_pure为纯净模式的截取字数，推荐字数为300。excerpt_link为阅读更多按钮展示与否的开关。
3.2.10 文章页问题
3.2.10.1 相关的文章
文章页将展示与当前文章具有相同分类、相同标签的系列文章，排序规则：分类>标签>时间>不相关文章。你可以决定是否使用该模块，posts_limit为显示的文章篇数，posts_excerpt为每篇文章的文字截取数量。
1 | # 04-POST |
info!
只有全站博客文章篇数大于1且relate.enable为真时，该模块有效。
3.2.10.2 阅读量计数
对于leancloud_count，你必须设置appid、appkey；对于busuanzi_count，你只需要开启它即可。
leancloud计数
- 打开 leancloud ，完成注册。
- 创建应用
- 配置LeanCloud
进入新创建好的应用，点击存储，这时需要创建名为Counter的class用来存储访问博客的数据，例如：访问次数，最新访问时间等信息。class类名必须为Counter，主要为了与next主题相兼容，否则无法接收到相关数据。为了避免后续因为权限的问题导致次数统计显示不正常，ACL权限选择无限制，具体配置如下图所示：
- 在所有应用中获取当前新建应用的
Appid、Appkey和REST API 服务器地址
- 修改博客根目录->themes->next->_config.yml文件
1 | # post_count |
- 卜蒜子计数
1 | busuanzi_count: |
该模块放置于页脚，文章页面只显示文章的阅读量，其他页面只显示总访问量和访客数
3.2.10.3 文章点赞
如果你完成了3.2.10.2阅读量计数的leancloud计数的设置，那么只需要开启like_post。
1 | # post_count |
3.2.10.4 文章排行
如果你完成了3.2.10.2阅读量计数的leancloud计数的设置，那么只需要开启topN_post。（文章阅读排行依赖于3.2.10.2阅读量计数）
1 | # post_count |
info!
该模块放置于搜索页面，你可按需定制
3.2.10.5 文章目录
若一篇文章的正文存在h1、h2、h3等标题，则文章页展示目录按钮。点击目录按钮，页面左侧展示文章目录。当屏幕宽度小于1024px或页面滚动高度大于文章正文高度时，页面隐藏文章目录。
1 | # post_toc |
3.2.10.6 数学公式
请先设置主题配置文件的mathjax参数
1 | # post_mathJax |
再于文章的Front-matter中添加mathjax: true想要修改Front-matter默认模板，参见3.3 博文配置。
1 | title: Annie主题使用说明 |
3.2.10.7 代码块复制
只有theme.code_copy.enable为真且config.highlight.enable为真时，代码块的复制功能才有效。
1 | # post_code |
3.2.10.8 文章评论功能
Hexo-theme-Annie主题集成了gitalk、DesertsP版的valine、livere评论插件。本博客使用gitalk。
| 序号 | 评论插件 | 使用方法 |
|---|---|---|
| 1 | gitalk | 正式文档、Annie主题使用Gitalk |
| 2 | valine | 正式文档、加个Valine评论系统 |
| 3 | livere | 为Hexo博客添加LiveRe评论系统 |
warning!
对于gitalk，你必须设置clientID、clientSecret；对于Valine，你必须设置appid、appkey；对于livere，你必须设置livere_uid。
3.2.10.9 文章分享功能
Hexo-theme-Annie主题集成了addThis、baiduShare、shareThis、socialShare分享插件。本博客使用socialShare。
| 序号 | 分享插件 | 使用方法 |
|---|---|---|
| 1 | addThis | 登录addThis获取应用的账户id |
| 2 | baiduShare | 直接使用 |
| 3 | shareThis | 登录shareThis获取应用的账户id |
| 4 | socialShare | 直接使用 |
info!
使用addThis、shareThis时，应注意关闭浏览器的内容拦截插件。
3.2.11 社交链接
直接增加相应的社交图标、社交链接即可。
1 | # social |
3.3 博文配置
修改scaffolds\post.md文件如下，确保new post能出现完整、正确、可用的头部。
文章的模板样例如下，cover即为文章封面图的路径，你可以使用相对路径或绝对路径。toc表示目录是否打开，mathjax表示是否适配公式，tags表示标签，最多只能有三个，catagories表示分类，有且只能由一种。
分类页的HEXO博客字段来源于文章Front-matter中的categories参数值，标签页的说明字段来源于文章Front-matter中的tags参数值。hexo博客框架只支持一个同级分类，支持多个同级标签。
1 | --- |
冒号后一定要有空格！
tags和categories都要先换行然后
- example，注意-号后要有空格
3.4 主题更新
如果你使用主题后，几乎未改动代码，那么可以使用下面的命令行更新主题。
1 | cd themes/Annie |
如果你使用主题后，自定义改动相当多的代码，推荐下载源码包以进行定制！
