技术

Github Pages(下)：使用Hexo博客生成工具

最近用 Hexo 搭建了工作网站，发现这个工具发文章就像是发朋友圈一样简单。虽然我以前用网页拼凑老网站，花了很多时间，但我还是决定换了，写作和发布体验还是很重要的。
我的理解是，这是一个自动生成静态（html+css+js）网站的工具，主题里是很多模块化的网页，可以通过.yml配置文件运用这些模块，把MarkDown(.md)博客批量转化为网页并且跟主页形成总分结构。
下面是我用Hexo搭建个人网站的过程和网站配置：

首先，一切以Hexo官网为准。

准备工作

配置Hexo文件夹

在mac上安装 Node/Npm

1
2
brew update
brew install node

（windows/linux用户参见此官方教程）

安装 Hexo

1
2
3
4
5
npm install hexo -g
hexo init blog
cd blog
npm install
hexo s

这时博客就在本地生成了。访问http://localhost:4000 可以看效果。
可以说Hexo是很强大的，默认主题网站结构合理，适配手机，搜索栏（google）也有了。只需要优化（改一下失效的链接，添加评论，RSS等模块）就行了。

（2021年6月更新：node的版本不能太高，不然会出现localhost可以看，但生成网页为空的问题）

基本操作

  • hexo g 生成/public 文件夹，里面是网站
  • hexo d 把这个网站文件夹推送到服务器
  • hexo clean 删除网站文件夹
  • hexo s 本地查看效果

配置文件

配置文件是两个，第一个是根目录的 _config.yml。重要配置有

  • language: zh-CN 是中文，不写是英文
  • url: https://hans2936.github.io （网站地址）
  • root: / (根目录在哪里，github就写斜杠，有些服务器会多一层路径)
  • skip_render: README.md 这样可以在 /source 里面放一个 README.md，推送的时候自动传到 Github 上面
  • theme: landscape 这里可以换主题

推送设置 (GitHub)

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

如果网站在服务器上，则可以用 rsync

1
2
3
4
5
6
deploy:
  type: rsync
  host: 服务器名
  user: 用户名
  root: 放网站的文件夹
  port: 22

第二个配置文件，是主题的配置文件 themes/landscape/_config.yml，主要有导航栏(menu)，侧边栏(widgets)，网站图标(favicon)等。

写新文章

1
hexo new "article name"

这条命令会在source/_posts产生新文件，然后改改文件名，在进入编辑MarkDown就行了。

每篇文章最上面是配置区，能用到的主要是

  • title: 题目
  • date: 日期 （会影响在主页的顺序）
  • tags: 标签
  • categories: 分类
  • updated: 修改日期

配置区下面就随便写了。值得一提的是，文章正文是支持html语言的，这样特殊字体和元素就可以直接加进去。

创建页面

1
hexo new page about

会在 source/about 里面产生新文件，跟文章是一样编辑的。
然后再从主题配置的导航栏里面加上这一页。

1
2
3
menu:
  ...
  关于: /about

引用图片

执行 npm install hexo-asset-image --save
然后，主配置文件 _config.yml 设置为

1
post_asset_folder: true

这个时候创建新文章就会产生一个同名文件夹，把图片放入即可。
然后在文章正文这样引用放进去的图片。 

1
![图片描述](文章名/图片名)

引用视频文件

对某个链接中的视频文件，可以执行 npm install hexo-tag-dplayer
这是一个播放器插件，使用时在文章中加入：

1
{% dplayer "url="  "pic=" "loop=yes" "theme=#FADFA3" "autoplay=false" "token=tokendemo" %}

其中 url 是视频地址，pic 是缩略图地址。

这个方法是引入视频的最佳方法，但是需要一个地方来存放这些文件（url）。
Github只有1G太少了，可以考虑使用阿里云oss存储，淘宝账户就能开，还很便宜。

引入第三方视频

对视频网站上的视频，可在Markdown文件中明码使用html语言 iframe，比如

1
2
3
<div class="selfadapting-video">
<iframe src="" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>
</div>

其中class="selfadapting-video" 是一个自适应长宽比例的容器，具体看这篇博客。

创建侧边栏

比如在 themes/landscape/layout/_widget/ 创建一个 about.ejs

1
2
3
4
5
6
7
8
<% if (site.tags.length){ %>
  <div class="widget-wrap">
    <h3 class="widget-title">About</h3>
    <div class="widget">
      E-mail: xyz@123.com
    </div>
  </div>
<% } %>

然后在主题配置的侧边栏中加上：

1
2
3
widgets:
- ...
- about

RSS 订阅

执行 npm install hexo-generator-feed 下载rss功能包，
然后在主配置文件 _config.yml 里面加上

1
2
3
4
5
6
plugin:
- hexo-generator-feed
feed:
type: atom
path: atom.xml
limit: 20

然后在主题配置文件里加上 rss: /atom.xml。

网上的教程都是这样的，但是当我实际加入的时候，发现rss软件里面的图片都是空的。
后来我找到了这个Fork of hexo-generator-feed，用它来替换官方的包，然后去掉包里面 atom.xml 里面的 cdata就可以了。
这个包还剩下一个bug是当程序框里的某一行code过长(出现左右拖动的功能后)，rss显示的code字体过大，但是不涉及编程的文章就没有问题了。

站点地图

类似上一条，执行 npm install hexo-generator-sitemap --save
主配置文件添加：

1
2
3
# Sitemap 
sitemap:
    path: sitemap.xml

然后提交给 Google Search Console 就行了。

高级修改 (评论，分享)

Hexo的网页其实是被拆开成很多零件的，主要在themes/landscape/layout/_partial/，
当在网页中加入一个新的模块时，比如对评论系统Gitment来说（关于Gitment见此教程），首先要打开 head.ejs 引用js, css文件（需放入themes/landscape/source）

（2019年12月更新：忽然发现Gitment不能用了，通过查看Gitment的Github项目Gitment issue 188解决了问题。又发现出现了类似的工具Gitalk。）

(2020年4月更新：发现上次解决方案重新push的时候还是有bug，改用 Gitalk 了，另外在外网，Disqus是可以用的。)

1
2
<link rel="stylesheet" href="/css/gitment.css">
<script src="/js/gitment.browser.js"></script>

然后在 article.ejs 里面加上 Gitment 的code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<% if (!index && post.comments){ %>
  <section id="comments">
  <div id="gitment"></div>
      <script>
      const gitment = new Gitment({
        id: '<%= post.date %>',
        owner: 'username',
        repo: 'username.github.io',
        oauth: {
        client_id: '---yourID---',
        client_secret: '---yourKey---',
        },
      })
      gitment.render('gitment')
      </script>
  </section>
<% } %>

就实现这个第三方功能了。注意 id: '<%= post.date %>' 这句话是为了修复网页路径过长不能显示评论的bug (在手机app内分享网页很容易出现长后缀)。

主题自带的功能也可以改，比如说分享功能可以在themes/landscape/source/js/script.js加一句，

1
'<a href="http://service.weibo.com/share/share.php?&title=' + encodedUrl + '" class="article-share-sina" target="_blank" title="微博"></a>'

然后找到themes/landscape/source/css/_partial/article.styl 比照着定义一个 .article-share-sina 就可以了。

像这种高级修改，对有一定网页知识的人来说有无限可能，自己做一个主题都是可以的。

本站的Hexo设置

  • 默认主题 Landscape。
  • 抬头图片位置banner.jpg：我家的猫。
  • 评论系统为Gitment，需要引用gitment.css, gitment.broser.js， 并编辑 article.ejs 和 head.ejs。
  • 分享按钮为自带按钮，包括Sina（改 script.js 和 article.styl）。
  • jquery.min.js 路径从google改为 https://cdn.bootcss.com/jquery/3.3.1/jquery.min.js (改 after-footer.ejs)。
  • 从 NexT 主题移植而来的本地搜索引擎，见下文。

补充篇：NexT本地搜索引擎的移植

Hexo 默认的 Landscape 主题其实已经很好了，可以说简明美观，网页上的元素也不难添加。
但是美中不足的就是用了谷歌搜索引擎，谷歌在国内打不开就不说了，而且用外部搜索引擎本来也不如站内搜索便捷实用。
后来我发现 NexT 主题是有站内搜索功能的，就试着把这个功能移植了进来。

本地搜索的原理

对于动态网站来说，可以通过 php 实现。
但是，GitHub博客是静态网站，用不了 php，导致我在老网站只能把google搜索结果页内置到了网站里面 （Landscape也用了谷歌）。

NexT 主题实现这个功能，用了 Hexo 的拓展包 hexo-generator-searchdb，它预先生成了一个文本库search.xml，然后传到了网站里面 。在本地搜索的时候，NexT直接用javascript调用了这个文件，从而实现了静态网站的本地搜索。

准备工作

首先把产生文本库的包安装好，执行 npm install hexo-generator-searchdb --save。
然后在主配置文件 _config.yml里面加上

1
2
3
4
5
search:
  path: search.xml
  field: post
  format: html
  limit: 10000

并且在主题配置文件加上

1
2
3
4
local_search:
  enable: true
  trigger: auto
  top_n_per_article: 1

其中trigger表示搜索结果会不会打字时自动显示，top_n_per_article 表示每篇文章最多显示几条结果（-1为不限数字）。
这些只是准备工作，在把代码放到Landscape 之前，这些设置不会起任何作用。

NexT 主题的本地搜索代码

NexT 主题的 local-search 主要是下面几个模块组成的：

Landscape主题的后缀有所不同（不是.swig， 而是.ejs），这几个文件copy过来之后需要稍微改一下语法，几个图标也需要重新定义，细节如下。

移植步骤

定义”搜索”，”关闭”，”无结果”等图标

NexT 大量使用了 <i class = "fa abc"> </i> 这样的方式来引用 FontAwesome 图标，但是 Landscape 却不支持这么用。
所以一开始不得不定义一些图标，在主题文件夹 themes/landscape/ 的 /source/css/ 下面找个地方 （比如说_partial/header.styl），定义：

1
2
3
4
5
#icon-close:before {
  font-family: FontAwesome;
  content: "\f146";
  font-size: x-large
}

这样就定义了一个关闭搜索框的图标。移植的时候重新定义图标为<span id="icon-close"></span> 就可以了。
新定义的图标主要是搜索 \f002，关闭\f146，和无结果 \f119。

放入调出搜索框的链接

首先进入主题文件夹的/layout/_partial/header.ejs ，那里默认有一个搜索链接（id="nav-search-btn" class="nav-icon"）。
把这个链接扩展为：

1
2
<% if(!theme.local_search.enable) { %><a id="nav-search-btn" class="nav-icon" title="<%= __('search') %>"></a><% } %>
<% if(theme.local_search.enable) { %><a href="javascript:;" class="popup-trigger nav-icon" id="nav-search-btn"></a><% } %>

这也就意味着用主题配置中的 local_search.enable 来控制搜索功能了，打开本地搜索的情况下，搜索链接会启动class="popup-trigger"，也就打开了本地搜索引擎。

放入搜索框

还是着刚才的文件header.ejs，可以在最后一行</header>前面加上

1
<% if(theme.local_search.enable) { %><div class="local-search-inner"><%- partial('search') %></div><% } %>

其中 <%- partial('search') %> 指向了 search.ejs，这个文件也就是 NexT 的搜索框另一个localsearch.swig了。
把它拷贝成search.ejs 跟 header.ejs 放在一起，但是图标要全部换成适配Landscape的定义。另外直接明码写上placeholder=" 本地搜索..." 就可以了。

放入核心 javascript

把localsearch.swig放入/layout/_partial/, 并且命名为localsearch.ejs。
然后在/layout/layout.ejs的最后，</body> 的上一行引用这个文件 <%- partial('_partial/localsearch') %>。
这个目的是在每一个网页的最下方加入这一段 javascript。

然后就要改这个文件了， 要改的有三项：

  • 图标
    跟刚才一样，凡是带class="fa abc" 的图标都要重新定义成适配Landscape的。
  • 语法
    改成 localsearch.ejs 之后，这个脚本里面的两类语法要改。 一是if..else..要这样用：
    1
    <% if (theme.local_search.enable){ %><% } %>
    二是config要这样调用（注意有个等号）：
    1
    var search_path = "<%= config.search.path %>" ;
    大概一共三四处要改，主要是config能读到就可以了。
  • 搜索框的位置
    这个脚本里面有一处容易坑的地方，就是这一行
    1
    $('.popup').detach().appendTo('.header-inner');
    注意这个.header-inner是搜索框的位置，是要根据情况改的。比如我刚才在header.ejs定义的是
    1
    <div class="local-search-inner"><%- partial('search') %></div>
    那就要把.header-inner 改为 .local-search-inner 了。

放入渲染文件，取消阴影背景

渲染文件也是必须的，可以把 localsearch.styl 放入 /source/css/_partial/
然后在主渲染文件/source/css/style.styl中，注意加上 @import "_partial/localsearch" 就可以了。

不知道什么原因，这个搜索引擎的阴影背景.local-search-pop-overlay 总是会出现在最上方，导致搜索框出来之后根本点不到。我直接给它设置 z-index: auto ，跳过了这个问题。

这个文件是大部分元素的渲染文件，可以用来调整图标位置，placeholder文字的大小等等，这都是细节了。

把原先的搜索功能关掉

原先的搜索能在 source/js/script.js 里面，把这一段code移到 localsearch.ejs 里面，然后用一个

1
<% if (!theme.local_search.enable){ %><% } %>

来控制就可以了。

总结

最终搜索的效果截图在这里：
本地搜索的效果
其实直接用 NexT 就好了，不过自己编辑主题可以趁机学习一下。毕竟还是成功了。
有一点很重要的是，自己编辑主题是免不了要debug的，要善用谷歌浏览器的检查功能（以及最简单的输出 console.log()，或者其他工具的同类功能）。