1 引言

Hexo 是一个简单、快速、强大的博客发布工具，支持 Markdown 格式，有众多优秀插件和主题。我一般使用 Markdown 语法编写文章，通过 Hexo 命令行工具生成静态网页，并通过 Hexo 部署到网站。

2 配置环境

安装 Hexo 之前先要安装 javascript 开发环境，因为怕麻烦，就直接使用了 Hexo 的 docker image 现成环境。具体版本用了轻量级且稳定的系统 alpine 版，整个镜像只有几十兆，其中还包含简单的 vi 编辑器。我的宿主机系统是 Ubuntu 22.04，具体操作如下：

1
2
3
4
$ docker pull taskbjorn/hexo:alpine-latest
$ sudo mkdir /exports/hexo_data -p # 数据存放在 docker 之外
$ sudo chmod 777 /exports/hexo_data
$ docker run -it --rm --name my_hexo_container --privileged=true -p 4000:4000 -v /exports/hexo_data:/home/hexo/.hexo taskbjorn/hexo:alpine-latest # 启动镜像

第一次运行时，数据安装到/home/hexo/.hexo 目录，比较慢，再启就快了。

正常启动后，使用 localhost:4000 即可在本机访问博客，生成新内容时自动更新，无需重启服务。

从另一个终端进入 docker container，以使用命令操作 Hexo：

1
$ docker exec -it my_hexo_container sh

进入 docker 内部可以看到，当前用户为 hexo，在当前目录下已经建立好了项目文件。

其中包安装在 node_modules 目录下，markdown 等源数据在 source 目录下，生成的文件在 public 目录下，主要配置文件是 _config.yml。

3 配置文件

_config.yml 是最基本的配置文件，至少需要设置其 site 部分：

1
2
3
4
5
6
title: '标题'
subtitle: '副标题'
description: '网站描述'
author: 作者
language: zh-Hans
timezone: 'Asia/Shanghai'

4 基本操作

1
2
3
4
$ hexo cl # hexo clean 清除缓存
$ hexo g # hexo generate 生成静态网页
$ hexo d # hexo deploy 部署
$ hexo s # hexo server 启动服务预览，由于docker已经启动了服务，无需此操作

5 Markdown 规范

通过 markdown 生成的网页，如果不设置文件头，则列表中只能显示文件创建日期：

因此，至少需要设置 title 才能正常显示，一般设置 title, author, date, tags，Obsidian 的 hexo 模板如下：

1
2
3
4
5
6
7
---
title: <% tp.file.title %>
author: xieyan0811
date: <% tp.file.creation_date() %>
updated: <% tp.file.last_modified_date() %>
tags:
---

6 部署博客到 github.io

6.1 配置 github 免密环境

1
2
3
$ git config --global user.email 你的邮箱
$ git config --global user.name 你的用户名
$ ssh-keygen -t rsa -C 你的邮箱 # 一路回车

如果提示找不到 ssh-keygen，可能是 docker 环境中未安装该软件，由于安装的是 alpine 环境，需要用 root 权限登入，才能安装软件（建议另起一终端操作）：

1
2
$ docker exec -u=root -it my_hexo_container sh # 以root方式登入
# apk add openssh # 安装 openssh 工具集

将 /home/hexo/.ssh/id_rsa.pub 内容加入 github，具体方法是：

https://github.com/settings/keys add ssh key

设置好后，查看能否正常使用：

1
$ ssh git@github.com  # 正常结果形如: You've successfully authenticated

为保留 docker 中的内容，建议设置后 commit 一下：

1
docker commit my_hexo_container taskbjorn/hexo:alpine-mine_230828

6.2 配置文件

修改配置文件 _config.yml，设置部署服务

1
2
3
4
deploy:
  type: 'git'
  repo: git@github.com:用户名/用户名.github.io # 注意这里不是http地址 
  branch: master

6.3 部署

1
2
3
$ npm install hexo-deployer-git # 安装 hexo 的 git 插件
$ hexo g # 生成静态网页
$ hexo d # 部署到 github.io

正常执行后，可以看到 public 目录内容被更新到 github.io 主页，内容也不多，只有 demo 时不到 1M。

7 显示图片

Hexo 支持多种显示图片的方法，比如图床，上传图片等，这里介绍最简单的方法：

7.1 安装插件

1
2
$ npm install hexo-asset-image
$ npm install hexo-renderer-marked

7.2 配置文件

保持 _config.yml 配置文件 中 post_asset_folder: false 不变，加入 marked 设置：

1
2
3
4
post_asset_folder: false
marked:
  prependRoot: true
  postAsset: true
  • 我在 Obsidian 中的图片都放在 attachments/ 目录下，将此目录复制到 Hexo 项目的 source 目录中，即：source/attachments/xx.png
  • hexo g 重新生成后，图片正常显示
  • 注意图片较少时，建议使用该方法，图片很多时，github 项目也变得很“重”，建议使用图床。

8 更换主题

建议设置一个常用的主题，比如 next，遇到问题也好查资料。

官网主题见：https://hexo.io/themes/

  • 安装主题
1
2
npm install hexo-theme-next # 安装在node_modules/ 目录下
cp node_modules/hexo-theme-next/_config.yml _config.next.yml # 复制主题配置文件
  • 修改配置：在 _config.yml 中，修改：theme: next
  • 重新生成后，即可看到新主题

9 调试

  • 查看软件版本
1
hexo -v
  • 查看详细 debug 信息
1
hexo g --debug # 加 --debug 参数

10 忽略一些文章

10.1 整体配置

修改 _config.yml，修改后注意先清缓存再生成，否则设置可能不生效。

1
2
3
4
skip_render:
  - '_posts/tools/*' # 目录下文件
  - 'tools/**' # 目录及子目录下文件
  - '_posts/**/*索引_*' # 跳过所有目录下包含 索引_ 关键字的文件

10.2 在 markdown 中配置

在.md 的文件头中设置 published 为 false

1
published: false

11 参考

如何让Hexo不渲染某些文件

hexo相对路径图片显示

hexo博客如何插入图片

markdown 文件头 hexo 相关项的配置说明