Hexo博客搭建(上)

1. 从MWeb到Hexo

我在公司的需求文档一直都是通过MWeb使用Markdown写好后一键生成静态页面,然后直接部署在公司的服务器上,算是个很简单的博客(需求文档)发布系统。但出于商业软件的闭源和小众,而且软件是个独立开发者开发,生成的静态网站的UI效果和用户体验总是不尽人意。联系开发者,反馈让我自己改改生成模板….

可能改一两个功能还是可以,但是没做过前端网页开发,可以想象无论怎么魔改估计也达到不一个比较理想的效果。

注1:MWeb的博客建站效果可以访问链接
注2:虽然刚刚吐槽了不少MWeb的不便之处,但本人还是非常喜欢使用它来编辑Markdown文档,写过不少于两百篇文档,强烈推荐

在多个方案的选择和折腾之后,选择使用Hexo。在不断的开坑和填坑下,还算是有些不错的收获,所以在这里分享记录一下。

2. 整个Hexo项目的结构

屏幕快照 2018-04-08 上午8.15.21

  1. Hexo本地项目为本篇所需求完成的事情,主要是完成Hexo项目的搭建和生成静态页面
  2. 在本地编辑好的静态页面要发布到服务器上,允许其它用户访问才能构成基本的网站服务,服务器Git服务器Nginx为下篇所描述的内容
  3. 通过互联网访问你的博客此部分只是补充描用户如何使用和观看你的博客

3. 解决问题记录

基本的Hexo项目初始化和使用说明本文就不再赘述,无论是官方还是非官方的文章已经到处都有描写了。

官方英文文档
官方中文文档

3.1. 新手注意的点

3.1.1. Hexo项目的文件夹结构

下图是我建立好的项目文件夹结构,除了结合上面的官方文档,再加入一些自己的理解进行说明。

屏幕快照 2018-04-07 下午8.37.44

名称 属性 相关命令 描述介绍
walnut 文件夹 Hexo init walnut 是当前博客项目的根目录,也是大部分是操作命令的主要目录
node_modules 文件夹 npm install [模块名] 当前项目所依赖的node.js模块
非全局,各个项目之间的模块安装包相互独立,不会互相影响
public 文件夹 Hexo g 生成项目的静态网页,用于发布到服务器使用,本地需要通过Hexo s来使用
scaffolds 文件夹 hexo new 新文章文件名 新建文章引用的模板存放位置,可以编辑
source 文件夹 hexo new 新文章文件名 博客内容的主题,之后写文章都会在这里
_drafts文件夹下的文章不会发表显示出来的
_posts放置文章
themes 文件夹 用于放Hexo主题,一个主题一个文件夹,之间互不影响
package.json 文件 npm install [模块名] 只说一次使用过程,一个旧的Hexo项目引入了错误的插件,复制一个新项目配置好的文件内容
_config.yml 文件 Hexo项目的主要配置之一,发布的网站地址,文件目录结构控制,主题选择等

3.1.2. 两个_config.yml

在 Hexo 中有两份主要的配置文件,其名称都是 _config.yml。 其中,一份位于站点根目录下(前文的/walnut/文件夹下),主要包含 Hexo 本身的配置;另一份位于主题目录下(前文件的walnut/themes/next/文件夹下,这份配置由主题作者提供,主要用于配置主题相关的选项。

大部分的中文文档中,将前者称为 站点配置文件, 后者称为 主题配置文件

3.1.3. 编辑主题和插件的时候注意备份

这个是在解决MathJax时遇到的,看了很多网上的解决方案,涉及到改框架的代码地方很多。结果多种改法混合后,不但问题没有解决,Hexo项目直接无法启动了。最终只好删除了测试项目,又重新开了个新的项目。

所以最好是使用git来对项目本身进行管理,Hexo项目本身是非常友好的支持git管理的。

3.2. 能解决90%问题的文章

参考文章: Hexo搭建个人博客–NexT主题优化

今天是2018-4-7,上面的文章的发布时间是2018-3-11。虽然有官方文档,但具体实操的时候还是会像我一样遇到各种问题。如果你能看到这篇文章,将会有比较全面的帮助。

3.3. 使用MWeb编辑Markdown的正确姿势 & 正确的在Hexo中引用图片

遇到的问题:

  1. 一般的Markdown文件对图片的管理做法是创建一个与MD文件同名的文件夹,然后在MD文件中对同名文件夹中的图片进行相对路径的引用。如果是这种引用方法,图片将只能在文章内可见,首页或者其它地方是无法引用的
  2. 如果是对于官方推荐的相对路径引用的标签插件,则我原来所有Markdown中的[]()图片全部都要重新编辑

解决参考:

MWeb配合Hexo高效管理博客

此方法的好处:

  1. 自动将引用的图片放入images文件夹中
  2. 之前MWeb的文档库结构只用拷贝过来,并将media改为images放入即可
  3. 图片的显示全局可用

Hexo在本地运行Hexo s的时候,MWeb似乎是不能读取图片,也不能往文章中进行图片导入,如果需要导入先停止Hexo的运行

3.4. MathJax的正常渲染

其实这个问题本来想单开一篇文章,因为跟网上的解决方案大相径庭。但实在是觉得这个解决方案很简单,就不水文章数了。按当前文章的发布时间,是不需要对官方的项目代码做任何修改就可以实现正常渲染的,所以一开始是走了非常多的弯路。

3.4.1. 解决办法

按以下三个步骤即可:

  1. blog的根目录运行npm install hexo-math --save
  2. blog的配置文件_config.yml末尾添加以下配置:
1
2
3
4
5
6
7
8
9
10
11
math:
engine: 'mathjax' # or 'katex'
mathjax:
src: "//cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
config:
# MathJax config
katex:
css: #custom_css_source
js: #custom_js_source # not used
config:
# KaTeX config
  1. 再运行一次npm install hexo-math --save

备注1:运行两次hexo-math的原理目前不清楚,但它确实有用
备注2:如果拿旧项目测试不行的或者改过代码的,可以开个新工程试一试

3.4.2. 运行效果图

3.5. 关于主题Next

以下为官方主页,但其引用的主题链接和git代码仓不是最新的

http://theme-next.iissnan.com/getting-started.html

1
2
3
4
# 非最新代码仓库

$ cd your-hexo-site
$ git clone https://github.com/iissnan/hexo-theme-next themes/next

6.0新版之后换成了git仓库,为下面这个地址

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

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

新的主题似乎正在制作中

3.5.1. 点击图片放大效果

Hexo项目初始化自带的landsapce主题是带图片缩放的,换成Next主题后,点击图片放大的效果就没了。查了一下需要加载fancybox插件

按照下面的步骤进行安装即可:

https://github.com/theme-next/theme-next-fancybox3

4. 总结

免费的永远不是最便宜的,但这种不停的给自己挖坑然后填坑,倒是给了自己不少写作的素材:P。

下期会讲解一下怎么把Hexo项目发布到私有VPS上。

0%