hexo搭建博客踩坑

发表于 | 更新于 | 分类于 | 阅读次数：

前言

hexo + next搭建时遇到一些问题，包括插入图片、toc、代码行号、首行缩进等。

推荐在对应github页面的issue板块搜索自己的问题，可以少走很多弯路。

环境安装

  • 安装git
  • 然后在合适的文件夹下执行命令：
1
2
3
4
5
npm install hexo-cli -g
hexo init blog
cd blog
npm install
hexo server

此时打开 http://localhost:4000 ，便可以看到hexo自带的主题。

在bolg文件夹下会有如下文件：

名称 说明
_config.yml 配置文件
node_modules hexo插件
public hexo g生成的文件
source md文件以及资源文件
theme 主题文件夹
db.json package.json package-lock.json json文件

配置github仓库

  • 申请github账号

  • 建立一个与自己用户名相同的仓库，即 username.github.io，username必须与你的用户名一致。

  • 修改hexo的_config.yml文件，将末尾的配置修改为：

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

主题选择

可以在知乎上找找别人推荐的主题，无意中看到有个2016年theme的排名：https://en.abnerchou.me/Blog/5c00ca67/ 。这里面的主题都还可以，样式简洁，功能全面。

我想要一个自带TOC目录、页面简洁、可以查看站点文章的主题，最后权衡下来选择了next主题。

yilia主题： https://github.com/litten/hexo-theme-yilia

next 主题： https://github.com/theme-next/hexo-theme-next

选择好主题后，在_config文件中，将theme改为主题名称即可启用主题。

hexo部署

下载部署插件npm install hexo-deployer-git –save

部署命令：

hexo clean 清理缓存

hexo generate/hexo g 本地生成

hexo deploy/hexo d 部署到远程仓库

或者使用hexo d -g直接部署

其他hexo指令

hexo new/hexo n 新建文章

hexo server/hexo s 启动服务，本地可通过4000访问

hexo version/hexo v 查看hexo版本信息

hexo help 查看帮助

image引入

hexo官网 https://hexo.io/zh-cn/

首先需要安装image插件

1
npm install hexo-asset-image --save

安装完成之后进入hexo\node_modules\hexo-asset-image文件夹，查看里面的readme文档，使用时要注意：

Make sure post_asset_folder: true in your _config.yml.

Just use ![logo](logo.jpg) to insert logo.jpg.

将hexo文件夹下的_config.yml文件的post_asset_folder属性改为true，利用hexo生成新的md文件时xxx.md时，会创建相应的xxx同名文件夹，资源文件放在文件夹中，利用hexo g命令时，便会将文件夹内的资源存在在public文件夹内index.html相同的文件夹内。因此插入logo.jpg图片时，只需要在md文件输入 ![logo](logo.jpg)即可。

  • 对于本地而言，图片应该存放在与md文件同名的文件夹内，例如:hexo n test

在 hexo\source\_posts文件夹下就会生成test.md以及test文件夹。只有将test.md所依赖的资源文件放在test文件夹，hexo g生成时，才可将资源文件放到正确的文件夹下。而在test.md中引用logo.jpg图片时，使用 ![logo](logo.jpg) ，在命令行输入hexo s运行hexo然后在 http://localhost:4000 查看发现图片可以正确引用。但是本地md文件却看不到图片。需要改成 ![logo](test/logo.jpg) 添加相对路径，本地才可引用成功（除非你把图片copy到md文件相同的路径下）。

将路径由 ![logo](logo.jpg) 改为 ![logo](test/logo.jpg) 后，执行hexo g命令，在对应的index.html文件中，image的路径解析为: 

1
<meta property="og:image" content="http://tru-xu.github.io/2019/05/12/test/logo.jpg">

这是正确的解析，自动添加日期并且logo.jpg实际存储位置与index.html中相同。

  • 采坑：**这里是个大坑，大部分的中英文的md文件名称都没有问题，但文件名包含某些特定字段的md文件，图片路径会解析失败。比如http。

当md文件名包含http时。例如hexo n httpXXX创建httpXXX.md文件，执行hexo g，查看对应的index.html中的图片路径：

1
<meta property="og:image" content="http://tru-xu.github.io/2019/05/12/httpXXX/httpXXX/logo.jpg">

图片路径中出现两个httpXXX，在网页点击F12，在源码中查看图片路径，路径中确实也是多出了一个httpXXX。图片路径错误，无法正常加载。

图片添加相对路径时，图片解析会出bug（也不能算bug，按照官方文档，图片路径只写图片名称不带相对路径时不会有问题，但这样本地编辑时就无法看到图片预览）。

这里由于我不是专业前端，所以没有细看hexo图像插件的源码。应该是路径替换时发生的问题。

toc 目录引入

  • 需要TOC支持的主题 yilia，icarus, indigo等。

toc安装文档地址：https://github.com/bubkoo/hexo-toc 

1
npm install hexo-toc --save

并修改hexo目录下的配置文件_config.yml文件,添加toc的相关配置，参数具体含义请查看上面链接里面的readme。

1
2
3
4
5
6
7
8
9
toc:
  maxdepth: 3
  class: toc
  slugify: transliteration
  decodeEntities: false
  anchor:
    position: after
    symbol: '#'
    style: header-anchor
  • 不需要TOC支持的主题，例如next

若使用next主题，安装hexo自带的toc后。next主题自带的toc会出现bug，点击toc目录无法跳转。在页面上F12查看next主题自带的toc链接，发现是#undefined。各种百度博客没啥用，最后早github的issue里面找到问题来源：

https://github.com/theme-next/hexo-theme-next/issues/380

hexo的toc插件导致next自带的目录无法跳转，将hexo-toc移除之后，此问题便可解决。

1
npm remove hexo-toc --save

代码块行号

远程：hexo配置文件_config.yml中的height里面的line_number改为true即可。

本地：typora的文件->偏好设置中找到代码块，选择显示代码块即可。

首行缩进

远程：themes\hexo-theme-next-master\source\css_custom\custom.styl 添加

1
.post-body p { text-indent: 2em; }

参考：https://github.com/iissnan/hexo-theme-next/issues/680

本地：编辑–>空格与换行–> 首行缩进

algolia搜索

官方参考链接

  1. 登陆algolia，注册账号或者使用github账号，本人使用github账号。

  1. 点击dashboard进如下面页面，点击indices，新建index，index命名随便写最好全英文。

  1. 配置权限：点击APIkeys->All API Keys，找到你的app对应的API key，点击edit，找到ACL，添加search、addObject、deleteObject、listIndexes、deleteIndex，点击update。

  1. 安装hexo-algolia插件
1
2
$ cd hexo
$ npm install --save hexo-algolia
  1. 修改本地站点_config.yml文件，
1
2
3
4
5
6
7
8
9
10
algolia:
  applicationID: 'your AppId'
  apiKey: 'your apiKey'
  indexName: 'your indexName'
  chunkSize: 5000
  fields:
    - title
    - slug
    - path
    - content:strip
  1. 更新上传Index。命令行以及输出如下所示
1
2
3
$ export HEXO_ALGOLIA_INDEXING_KEY= Your Search-Only API key # 使用 Git Bash,使用windiws的cmd会出bug
$ hexo clean
$ hexo algolia
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
$ hexo algolia
INFO  [hexo-algolia] Testing HEXO_ALGOLIA_INDEXING_KEY permissions.
INFO  Start processing
update link as:-->/2019/05/12/collections/LinkedList.PNG
update link as:-->/2019/05/12/collections/ArrayList.PNG
update link as:-->/2019/05/12/collections/LinkedList.PNG
update link as:-->/2019/05/12/collections/ArrayList.PNG
update link as:-->/2019/05/11/Http-note/网络分层.png
update link as:-->/2019/05/11/Http-note/中间设备.png
update link as:-->/2019/05/11/Http-note/Http传输.png
update link as:-->/2019/05/11/Http-note/wireshark-capture.PNG
update link as:-->/2019/05/11/Http-note/各层头部.png
update link as:-->/2019/05/11/Http-note/proxy
update link as:-->/2019/05/11/Http-note/网络分层.png
update link as:-->/2019/05/11/Http-note/中间设备.png
update link as:-->/2019/05/11/Http-note/Http传输.png
update link as:-->/2019/05/11/Http-note/wireshark-capture.PNG
update link as:-->/2019/05/11/Http-note/各层头部.png
update link as:-->/2019/05/11/Http-note/proxy
INFO  [hexo-algolia] 9 records to index (post, page).
INFO  [hexo-algolia] Indexing chunk 1 of 1 (9 records)
INFO  [hexo-algolia] Indexing done.
  1. 至此已完成上传操作，可以在algolia网站indices页面中找到对应的文件。切换到 NexT 目录，并安装 algolia-instant-search 到 source/lib 目录。
1
2
$ cd themes/next
$ git clone https://github.com/theme-next/theme-next-algolia-instant-search source/lib/algolia-instant-search
  1. 修改主题配置文件，在配置文件中找到algolia_search，将enable改为true。注：关闭其他搜索插件。

  • 问题：

  1. 无内容上传到algolia：
1
2
3
4
5
INFO 0 posts collected
INFO Clearing index on Algolia...
INFO Index cleared
INFO Indexing posts on Algolia...
INFO Indexation done. 0 posts indexed.

执行命令顺序如下所示，否则无内容上传到algolia上。

  • Hexo clean

  • hexo algolia