hexo 部署博客的使用笔记

发表于 2020-03-13 更新于 2025-02-05 分类于学习实践笔记

Hexo 的使用笔记。把博客布置在 Hexo 上，非常美观好用。这只是我自己用到的一些命令，肯定不全。还是多看看官方文档比较好。

hexo 的安装

hexo 需要有 node 和 git 环境。

安装好依赖，即可通过 npm 安装 hexo：

npm install -g hexo-cli

hexo 项目的初始化

进入要存放 hexo 项目的文件夹，运行命令初始化创建一个 hexo 项目：

cd /tmp/hexo
hexo init
 # hexo也可以初始化到指定文件夹：
hexo init /tmp/hexo

在项目文件夹中运行命令，会自动根据刚刚生成的 package.json 文件安装 npm 依赖的包：

npm install

博客文章 md 文件保存在 source/_posts 目录下，模板文件保存在 theme 文件夹中，_config.yml 为配置文件。

hexo 的命令写法

以下的命令，如无说明，都是默认在刚刚初始化的 hexo 的文件夹下进行的。

hexo 命令会在当前文件夹即其外层文件夹中寻找。若有 hexo 项目，则可正常运行。若无 hexo 项目，需要指定 hexo 项目的文件夹：

hexo --cwd /tmp/hexo server

创建博客

可以使用命令创建博客：

hexo new [layout] <title>

可以在命令中指定文章的布局（layout），默认为 post，可以通过修改 _config.yml 中的 default_layout 参数来指定默认布局。

命令执行后，会在 source/_posts 目录下生成一个 md 文件。

也可以自己创建 md 文件，在最顶端加上下面几行内容：

---
title: 文章标题
date: 2020-02-12 14:30:24
tags: 标签
toc: true
categories: Web 前端
layout: single-column
---

设置图片位置

打开配置文件 config.yml ，把下面的这一行设置成 true：

post_asset_folder: true

创建与 md 文件同名（不要 .md 后缀）的文件夹，把图片保存到里面。

在需要使用图片的位置，写上下面的格式：

{% asset_img slug [title] %}
# 例如
{% asset_img example.jpg This is an example image %}

模板下载

安装主题和渲染器（GitHub 访问太慢，已经转移至码云）：

git clone https://gitee.com/shuoliuchn/maupassant-hexo.git themes/maupassant
npm install hexo-renderer-pug --save
npm install hexo-renderer-sass --save

编辑 Hexo 目录下的 _config.yml，将 theme 的值改为 maupassant。

更多配置信息，参见： https://www.haomwei.com/technology/maupassant-hexo.html

模板修改

原版的模板使用 single-column 模式输出，没有目录展示。修改代码，让其支持目录。

打开 theme/manpassant/layout 目录下的 single-column.pug 文件，将其内容修改为：

extends base-without-sidebar
block title
  title= page.title + ' | ' + config.title
block content
  if page.toc
    div(class='clear')
      div(id='toc' class='toc-article')
        div(class='toc-title')= __('contents')
        != toc(page.content, {list_number: theme.toc_number})
  .post
    h1.post-title= page.title
    .post-content
      != page.content
  if page.comments
    include _partial/comments.pug

修改配置文件

如果 md 文件中有一对大括号之类的代码，部署博客时可能会出现莫名其妙的错误。这是因为 hexo 有一些参数，就是通过下面的符号来占位的：

{{ }}
{# #}
{% %}

要避免这样的问题，我们当然可以通过转义的方式来修改：

{% raw %}
{{ 双大括号内包裹的内容 }}
{% endraw %}

但是这样做并不合适，尤其是当我们写 django 的模板渲染或者 vue 的前端渲染语法的时候，因为我们会经常用到这些类似的符号。如果每一个都转义一下，好麻烦的。

所以，我更倾向于一劳永逸的，使用修改配置文件的方式规避这个问题。

打开文件 node_modules/nunjucks/src/lexer.js

找到这样两行代码：

var VARIABLE_START = '{{';
var VARIABLE_END = '}}';

将其修改为：

var VARIABLE_START = '{$';
var VARIABLE_END = '$}';

部署上线

编译：

hexo generate
# 可简写为：
hexo g

运行服务，服务默认运行在 4000 端口，绑定 0.0.0.0 的 IP 地址：

hexo server
# 可简写为：
hexo s
# 后台运行：
hexo s &
# 可指定端口：
hexo server -p 5000
# 亦可指定 ip：
hexo server -i 192.168.1.1

要将服务传至 GitHub 或码云，需要先建立仓库。

安装 npm install hexo-deployer-git --save 工具：

npm install hexo-deployer-git --save

修改配置文件中的 git 信息：

deploy:
  type: git
  repo: <repository url> #https://bitbucket.org/JohnSmith/johnsmith.bitbucket.io
  branch: [branch]
  message: [message]

修改完毕后，可以部署博客了：

hexo g
hexo deploy
# 可简写为：
hexo d
# 两条命令可以合并为：
hexo g -d
# 或
hexo d -g

设置博客首页置顶

先卸载掉原来的首页生成器，然后安装有指定功能的首页生成器

npm uninstall hexo-generator-index --save
npm install hexo-generator-index-pin-top --save

在文章的头部的 front-matter 中设置 top: true 即可。

设置 hexo 后台运行

每次都用 hexo s 命令启动博客很麻烦，而且一旦关闭终端，进程也自动终止。虽然按照官方方法，通过命令 hexo s & 可以实现后台运行，但是持续时间不到一天就会莫名其妙地关闭终止掉。好在在网上找到了合适的解决方案，思路是使用 pm2 工具让 hexo 进程时刻保持运行状态。

首先，安装 pm2：

npm install -g pm2

安装完成，进入 hexo 的根目录，创建一个 js 文件，比如 hexo_run.js

cd /tmp/hexo
vim hexo_run.js

在里面写上让进程保持运行的代码，写好后保存并推出：

const { exec } = require('child_process')
exec('hexo server',(error, stdout, stderr) => {
        if(error){
                console.log('exec error: ${error}')
                return
        }
        console.log('stdout: ${stdout}');
        console.log('stderr: ${stderr}');
})

用 pm2 运行 hexo_run.js：

pm2 start hexo_run.js
pm2 stop/restart hexo_run.js    # 停止/重启

pm2 常用命令：

pm2 list    # 查看pm2进程
pm2 -h      # 查看帮助

编辑页脚

页脚要通过模板的 footer 组件编辑。我的模板 footer 组件放在这里，对于不同的模板，footer 的存放位置和编辑方式是有差异的，这一点一定要注意：

vim themes/maupassant/layout/_partial/footer.pug

footer.pug 文件最开始的版本为：

#footer= 'Copyright © ' + date(Date.now(), 'YYYY') + ' '
  a(href=url_for('.'), rel='nofollow')= config.title + '.'
  |  Powered by
  a(rel='nofollow', target='_blank', href='https://hexo.io')  Hexo.
  a(rel='nofollow', target='_blank', href='https://github.com/tufu9441/maupassant-hexo')  Theme
  |  by
  a(rel='nofollow', target='_blank', href='https://github.com/pagecho')  Cho.

在最后加上个 a 连接，完整版本就是：

#footer= 'Copyright © ' + date(Date.now(), 'YYYY') + ' '
  a(href=url_for('.'), rel='nofollow')= config.title + '.'
  |  Powered by
  a(rel='nofollow', target='_blank', href='https://hexo.io')  Hexo.
  a(rel='nofollow', target='_blank', href='https://github.com/tufu9441/maupassant-hexo')  Theme
  |  by
  a(rel='nofollow', target='_blank', href='https://github.com/pagecho')  Cho.
  |
  a(rel='nofollow', target='_blank', href='http://beian.miit.gov.cn')  辽ICP备20001451号

保存退出，重新生成即可。

数学公式

若文章中出现了数学公式，可以使用