0%

Hexo博客踩坑笔记

Hexo提供了非常方便的Markdown写作方式,我们只需提供md文件,而Hexo则为我们生成个人博客并渲染md成为文章。因为生成的网页为全静态文件,所以可以很方便地部署到github pages上,省去了维护vps的麻烦。此文用来记录一些注意事项,就是我在部署博客时花费较长时间解决问题的笔记,方便日后参考。
注意当前Hexo版本更新到5.1.1,NexT更新到8.0.0。

配置

Hexo在更新到5.0后,配置结构发生变化,NexT在8.0也有许多调整,因此选择转移原内容到一个新项目。将hexo-cli更新到最新版本再建立新项目:

1
2
3
npm update hexo-cli
hexo init blog
cd blog

然后查看package.json,确认Hexo版本在5.0以上。接着将配置文件.config.yml和原博客配置对比进行更新,并且将注意配置为NexT:

1
theme: next

接着安装NexT并将配置模板复制出来:

1
2
git clone https://github.com/next-theme/hexo-theme-next themes/next
cp themes/next/_config.yml _config.next.yml

参考NexT文档。这样NexT主题的配置内容只需要修改_config.next.yml文件即可,且未修改的配置条目可以直接删除。
之所以选择git方法而不是直接用npm安装主题,是因为如果主题修复了什么重要的issue,可以通过git及时应用修改,而不用等新版本发布。

其他依赖

下面是我用到的所有依赖,取自package.json

1
2
3
4
5
6
7
8
9
10
11
12
13
"hexo": "^5.1.1",
"hexo-deployer-git": "^2.1.0",
"hexo-generator-archive": "^1.0.0",
"hexo-generator-category": "^1.0.0",
"hexo-generator-index": "^2.0.0",
"hexo-generator-searchdb": "^1.3.2", // local search
"hexo-generator-sitemap": "^2.1.0", // sitemap for google, baidu, ...
"hexo-generator-tag": "^1.0.0",
"hexo-renderer-ejs": "^1.0.0",
"hexo-renderer-markdown-it-plus": "^1.0.4", // for katex
"hexo-renderer-stylus": "^2.0.0",
"hexo-server": "^2.0.0",
"hexo-word-counter": "0.0.2" // word counter

写作

首页摘要

在文章某处加入<!-- more -->,那么此处前边内容会成为摘要,如果点击“阅读全文”则会在打开文章后自动定位到此处。

插入图片

一般用CDN,但考虑到我们内容并不多,所以我选择和文章放在一起。把配置文件post_asset_folder改为true,这样新建文章的时候会在同目录下有个同名文件夹,把图片放到文件夹里面。使用以下命令来插入图片。

1
{% asset_img example.jpg This is an example image %}

插入公式

NexT对数学公式提供了需要时才加载JS的解决方案。修改主题配置文件,启用every_page,在需要数学公式的md文件的front-matter中加入mathjax: true即可。建议使用katex,那么除了把katex的enable打开之外,还需要以下操作:

1
2
npm uninstall hexo-renderer-marked
npm install hexo-renderer-markdown-it-plus --save

如果之前已经生成过文档,需要清空重来:

1
hexo clean && hexo g

站内引用

引用站内其他文章,可以使用绝对链接,也可以使用如下语法。

1
{% post_link 文章名 描述 %}

文章链接

文章链接默认是使用文章标题的,可能非常冗长,不好看,尤其是中文标题的文章。Hexo提供了一个Permalinks的功能,可以自定义文章的链接。新版本Hexo推出12字符长度的hash选项,文章数量不过万的话冲突概率极小,基本够用了。如果需要进一步缩短链接长度,可选方案:friendly-link, abbrlink2

我的方案:修改node_modules/hexo/lib/plugins/filter/post_permalink.js文件,在变量meta中添加:

1
date_abbr: Math.floor((data.date.unix()-1377964800)/3600).toString(36)

这是因为我确认文章创建时间都在2013年9月1日之后,并且同一个小时内不会创建两篇文章。最后在.config.yml里配置

1
permalink: :date_abbr/

即可。方案与上面的可选方案一类似,但可选方案一无法正确解析文章内的资源文件路径。

外观

分类目录页面

参考Custom Pages

404页面

需要自定义404的话,直接在source下新建404.md即可。设计404界面有两种方案,一种是把front-matter的layout设置为false,这样整个页面重新写过。第二种是我的方案,继承原主题风格,只要写内容就行。区别于普通文章,设置内容开头如下:

1
2
3
4
5
6
7
8
9
10
---
sitemap: false
comments: false
sidebar: false
toc:
enable: false
---
<script type="text/javascript">
document.title = "404 Not Found";
</script>

评论系统

多数评论系统不是被墙就是被关闭,目前还算好用的就是基于github issue设计的。我使用gitalk。

部署

代码双线路同时部署到github和七牛云上:境外访问的IP跳转github pages,而境内则使用七牛云,保证国内外访问都稳定和快速。为了七牛云使用方便,应使用http而不是https。

部署到github

在config中配置如下:

1
2
3
4
5
deploy:
- type: git
repo:
github: git@github.com:Aqua-Dream/aqua-dream.github.io.git
branch: master

这样用hexo d可以自动更新文件到github仓库上。为了能自定义域名,在source文件夹下加入CNAME文件,内容仅一行,为自己的域名(aqua.hk.cn)。此外还需去github对应仓库上设置,在Custom domain中填入域名并保存。

部署到七牛云

先去下载qshell并放到hexo项目根目录下。在七牛账户的密钥管理中找到自己的密钥,然后命令行输入如下内容以添加账户:

1
qshell account ak sk name

在根目录内新建配置文件qupload.json并输入

1
2
3
4
5
6
{
"src_dir": "public",
"bucket": "aqua-blog",
"overwrite" : true,
"rescan_local" : true
}

最后在package.json里添加scripts

1
"publish": "hexo deploy && qshell qupload qupload.json"

使用npm run publish即可直接部署。本节参考将hexo博客一键部署到七牛云

Sitemap

1
npm install hexo-generator-sitemap

在config最后新增

1
2
sitemap:
path: sitemap.xml

提交sitemap前注意:部分页面不想被收录的需要在front-matter前加sitemap: false,比如404页面,比如站点确认文件等等。
此外在.config.yml中设置url: http://aqua.hk.cn,其中http不可以省略,否则对这里有影响。