为什么选择 Hexo

在选择 Hexo 之前尝试过其它方法：

  • CSDN、博客园、Blogger：免服务器、无需技术基础，但是可定制性低。CSDN 存在文章版权问题；博客园可能随时倒闭；Blogger是谷歌的，还是有关闭的可能性。

  • WordPress、Typecho：需要自己买服务器，备案网站等。

  • Webflow、Wix：国内讨论度低，并且它们的目标群体更偏向电子商务。

权衡之下最终选择了 Github Pages + Hexo 的方法，利弊如下：

  • ✅Hexo 在配置完成后就可以快速部署

  • ✅Hexo 支持 Markdown 语法

  • ✅Hexo 可自定义的主题和插件较多

  • ✅Hexo 在本地部署完成后上传到 Github Pages。即使没有了 Github，也不影响 Hexo 的本地数据

  • ✅使用 Github Pages 免费，且无需自己买服务器、备案网站等。

  • ❌中国大陆网络打开 Github Pages 页面较慢，需自备梯子。

  • ❌使用 Github Pages ，仓库必须是 Public(公开) 的，所以任何人都可以 Fork（Private(私人)仓库创建 Github Pages 需要 GitHub Pro）

  • ❌Github 虽然是存储开源代码的网站，但网站本身是微软的产品，仍受到微软相关协议的影响（比如在接到相关投诉后有权利删库）

权衡好利弊之后，就可以开始下一步。

搭建 Hexo

环境配置

需要安装以下软件：

  • Node.js (必需。Node.js 版本不能低于 10.13，建议使用 Node.js 12.0 及以上版本)

  • Git（必需。但如果不想上传到 Github Pages，仅在本地部署就不需要了）

  • PowerShell + Terminal（非必需，但个人推荐 Win10 和 Win11 用户安装）

第一步，安装 Node.js ，一直下一步即可（其中已经内置了 npm）。

安装完成后，可以在 PowerShell 里使用以下命令查看 Node.js 版本：

1
node -v

可使用以下指令查看 npm 版本：

1
npm version

第二步，安装 Git 并选择默认编辑器（我自己用 VSCode，当然不选也没问题）

安装完成后，可以在 PowerShell 里使用以下指令测试一下：

1
git --version

有些时候使用 npm 命令可能下载不了插件，必要时需要更换 npm 源：

1
npm config set registry https://mirrors.huaweicloud.com/repository/npm/
npm 官方原始镜像网址是：https://registry.npmjs.org/
淘宝 NPM 镜像：http://registry.npmmirror.com
阿里云 NPM 镜像：https://npm.aliyun.com
腾讯云 NPM 镜像：https://mirrors.cloud.tencent.com/npm/
华为云 NPM 镜像：https://mirrors.huaweicloud.com/repository/npm/
网易 NPM 镜像：https://mirrors.163.com/npm/
中国科学技术大学开源镜像站：http://mirrors.ustc.edu.cn/
清华大学开源镜像站：https://mirrors.tuna.tsinghua.edu.cn/
腾讯，华为，阿里的镜像站基本上比较全

安装 Hexo

当以上环境配置完成后，就可以安装 Hexo 了。

打开 PowerShell，使用 npm 命令安装 Hexo：

1
npm install -g hexo-cli

如果遇到 npm 提示升级，无视即可。

创建博客

初始化目录

找一个合适的新建文件夹（不能包含中文），比如 E:\Blogs\，作为博客的根目录。

如果此前已经安装了PoweShell 和 Terminal，只需要在这个文件夹里右键，选择「在终端(PowerShell)中打开」 。

在终端里面输入以下指令开始初始化：

1
hexo init

程序会从这个网址下载所需文件，如果报错，请使用以下命令再安装一次

1
npm install

简单解释这些文件夹和文件的作用：

  • .github

    • Github 相关配置，不用管。

  • node_modules

    • 该文件夹用于存放 Hexo 及其插件的依赖项。
    • 依赖项由 npm install 安装，通常不需要手动修改。

  • public（生成后出现）

    • 存放 hexo generate 命令生成的静态网页文件。
    • 这些 HTML、CSS、JS 文件会被部署到服务器（如 GitHub Pages）。
    • 你可以通过 hexo server 命令在本地访问这些页面。

  • scaffolds

    • 存放文章模板（脚手架），定义 hexo new 创建新文章时的默认结构。
    • 可以修改 post.md 以更改新文章的默认格式。

  • source

    • 该目录用于存放博客的内容，包括文章、页面、资源等。
    • 子目录 _posts 存放博客文章，文章以 Markdown (.md) 格式编写。
    • 子目录 _draft 存放博客草稿，此文件夹内的文章不会被发布。

  • themes

    • 存放博客主题。默认情况下，有 landscape 主题。
    • 你可以下载和更换主题，将新主题放入该文件夹，并修改 _config.yml 进行配置。

  • .gitignore

    • Git 忽略文件，防止提交不必要的文件，如 node_modules 和 public。

  • _config.landscape.yml

    • 这个是主题专属的配置文件，适用于 Hexo 默认的 landscape 主题。
    • Hexo 允许主题使用单独的 _config.yml 文件来管理主题相关的设置，而不会影响全局配置。

  • _config.yml

    • Hexo 的全局配置文件，包含博客的基本设置，如站点名称、URL、主题、部署方式等。
    • 是 Hexo 最重要的配置文件之一，需要手动编辑以满足个性化需求。

  • db.json

    • 记录 Hexo 生成的缓存信息，加快生成速度。
    • 可安全删除，Hexo 运行时会自动重新生成。

  • package.json（Hexo 项目配置文件）

    • 定义了 Hexo 博客的项目信息，包括所需的 npm 依赖（如 Hexo 核心和插件）。
    • 项目名称、版本、描述等信息。
    • dependencies（依赖项）：列出了 Hexo 及其插件，例如 hexo, hexo-generator-index 等。
    • scripts（脚本）：定义了一些快捷命令，如 hexo server。
    • 如果要安装新的插件（如 SEO 插件），可以运行 npm install 插件名 --save，然后它们会被添加到 package.json 中。

  • package-lock.json（依赖锁定文件）

    • 这个文件会随着 package.json 一起出现，用于锁定 npm 依赖的版本，确保在不同环境下安装时保持一致。
    • 你通常不需要手动修改它，它会在运行 npm install 时自动更新。

启动 Hexo 服务

1
2
3
4
5
hexo new test_my_site //创建一篇文章（带标题）

hexo g //生成静态文件

hexo s //启动服务，默认地址为 http://localhost:4000/

然后就可以在浏览器里，打开 http://localhost:4000/ 查看在本地部署好的 Hexo。

发布到 Github Pages

新建仓库

登录 Github 账号后，点击网页右上角的 ➕号（Create new…），选择 New repository。

Repository name 一栏中，按照 Github用户名.github.io 的格式填写。

仓库选择 Public(公开)，然后点击右下角绿色按钮 Create repository。

配置 SSH Keys

注意：长期不使用可能导致 SSH Keys 失效，需要重新配置 SSH Keys

任意文件夹右键菜单选择 Git Bash Here

输入以下命令：ssh-keygen -t rsa -C "你的GitHub注册邮箱"

敲几次回车后，它会告诉你：

Your public key has been saved in /C/Users/<用户名>/.ssh/id_rsa.pub

在 C:\Users\<用户名>\.ssh 目录下找到 id_rsa.pub，并用记事本打开。

点自己的 Github 头像 → Settings → SSH and GPG keys → New SSH Key

将 id_rsa.pub 的内容全部复制并粘贴到 KEY 文本框里，再点击 Add SSH Key，一个新的 SSH Key 生成。

完成后在 Git 终端输入 ssh -T git@github.com 验证是否连接成功

一键部署

注意：这里采用 Hexo 官方文档的一键部署教程，不会将源文件夹里的文件上传到 GitHub。

用 VSCode 打开在 Hexo 根目录的 _config.yml 文件，配置 deploy

1
2
3
4
deploy:  
  type: git  
  repo: <repository url>   ## 推荐选择 SSH 链接
  branch: main             ## 如果不希望放在主目录里，也可以自定义，比如 gh-pages

关于 repository url，在仓库的右上角点击 Code，找到 SSH 链接。

branch 参数也可以填写其他分支，在库的 Settings —— Pages 中设置

接下来，在 Hexo 根目录下启动 Git Bash，输入命令安装 hexo-deployer-git

1
npm install hexo-deployer-git --save

接着使用 hexo clean 清理缓存，使用 hexo d 部署到 Github 上

第一次部署，终端提示需要账号和邮箱，运行以下命令：

1
2
git config --global user.email "you@example.com"
git config --global user.name "Your Name"

之后再运行 hexo clean 和 hexo d ，弹出窗口提示，选择 Sign in with your browser，在浏览器里将 Git 与 Github 关联。

链接成功后，在浏览器的地址栏里输入：用户名.github.io，就可以访问了（可能有几分钟的延迟才能生效）。

撰写博客

通常来说，可以使用 hexo new + 文章标题来新建一个 markdown 文件。但我个人认为不如直接手动新建更方便。

定位到文件夹 Hexo根目录\source\_posts，里面放着的就是所有的文章，只需要新建一个文本文档，扩展名为 .md 就可以作为一篇新文章。

注意：使用 hexo new 生成的 markdown 文件和文章的 title 属性可以不一样，所以建议生成的 markdown 文件名里面不要带空格。

如果想写一篇文章，但是暂时不想发布，就放在 Hexo根目录\source\_drafts 文件夹内。

在文章撰写开始前，可以在每篇文章的开头附上 Front-matter ，其中包含了文章的基本信息（此信息也可以被 Obsidian 识别）：

1
2
3
4
5
6
7
8
9
10
11
12
13
---
title: test                ## 文章标题
date: 1970-01-01 00:00     ## 文章创建日期
updated: 1970-01-01 00:01  ## 文章更新日期
tags:                      ## 标签
  - aaa
  - bbb
categories:                ## 分类
  - ccc
  - ddd
abbrlink: abcdefgh         ## 使用hexo-abbrlink插件生成的永久链接
published: true            ## 是否发布。默认_posts为true，_drafts为false
---

此外，Front-matter 也可以根据主题增删参数，比如 butterfly 主题。

编辑工具

通常来说我会使用以下软件：

  • Obsidian（编辑文章）

  • VSCode + markdownlint插件（markdown 语法检查）

只要将 _posts 文件夹作为 Obsidian 的仓库之一，就可以在 Obsidian 里面编辑 Markdown 文件。这样做的利弊是：

  • ✅Obsidian 可以通过快捷键、自动补全等功能，让写markdown语法更加便捷

  • ✅Obsidian 所见即所得，更快地看到排版效果

  • ❌Obsidian 具有一些专属的 markdown 语法，和 Hexo 不兼容，需要自行修改

为了适应 Hexo，Obsidian 需做出如下配置：

  • ⚙文件与链接 —— 关闭【使用 wiki 链接】

  • ⚙文件与链接 —— 内部链接类型——基于当前笔记的相对路径

另外使用 VSCode 检查 markdown 语法属于是比较强迫症的事，个人不是很推荐。

文章整理

如果文章写得多，通过 Hexo 主题里带有的归档功能，能够把文章按照日期归档。

但是具体到电脑里的文件，在 _post 文件夹内会堆积大量文件。

目前我个人采取的方法：

修改创建新文章时的名称

1
2
3
# _config.yml

new_post_name: :year/title.md

这样，使用 hexo new 创建新文章时，会自动放到对应年的文件夹内。

分类和标签

Categories（分类） Tags（标签）
层级关系 ✅ 有（支持父子分类） ❌ 没有（都是平级的）
适用范围 📂 适用于大的分类（如技术、生活） 🏷 适用于具体的关键词（如 JavaScript、Vue）
单个文章数量 ⛔ 建议 1-2 个分类 ✅ 可以有多个标签
展示方式 📌 /categories/ 页面展示分类列表 🔖 /tags/ 页面展示标签云
SEO 作用 🔥 有利于结构化内容 ⭐ 有助于文章索引和搜索

文章加密

使用 hexo-blog-encrypt 插件。

输入以下命令安装：

1
npm install hexo-blog-encrypt --save

修改文章的信息头：

1
2
3
4
5
6
7
8
9
10
11
---
title: Hello World
tags:
- 作为日记加密
date: 2016-03-30 21:12:21
password: mikemessi
abstract: 有东西被加密了, 请输入密码查看.
message: 您好, 这里需要密码.
wrong_pass_message: 抱歉, 这个密码看着不太对, 请再试试.
wrong_hash_message: 抱歉, 这个文章不能被校验, 不过您还是能看看解密后的内容.
---

图片处理

图片存放

比较普遍的是两个方案：

  • 图片上传到图床（云端方案）

    • ✅文件放在服务器，节省本地空间
    • ✅通常没有存储限制
    • ❌隐私泄露风险
    • ❌非国内服务器，导致图片加载缓慢
    • ❌图床网站跑路，导致文件丢失

  • 图片留在电脑里（本地方案）

    • ✅文件更安全，不易丢失
    • ✅更方便地管理文件
    • ❌图片占用存储空间
    • ❌硬盘故障导致数据丢失
    • ❌发布文章仍需要上传图片，占用自己的网络存储空间

网络图床：

Github 搭建图床：https://blog.csdn.net/qq_44231797/article/details/131658184

选择本地存储，可以尝试图片转码压缩：

  • caesium。适合Windows 的开源软件

  • imagemagick。命令行工具，可调参数较多。

插入图片

资源（Asset）代表 source 文件夹中除了文章以外的所有文件，例如图片、CSS、JS 文件等。

全局资源文件夹

如果你的Hexo项目中只有少量图片，那最简单的方法就是将它们放在 source/images 文件夹中。 然后通过类似于 ![](/images/image.jpg) 的方法访问它们。

优劣如下：

  • ✅操作便捷

  • ❌难以对资源文件进行统一管理

文章资源文件夹

对于那些想要更有规律地提供图片和其他资源以及想要将他们的资源分布在各个文章上的人来说，Hexo也提供了更组织化的方式来管理资源。 这个稍微有些复杂但是管理资源非常方便的功能可以通过将 config.yml 文件中的 post_asset_folder 选项设为 true 来打开。

1
2
3
# 修改 _config.yml 配置

post_asset_folder: true

当资源文件管理功能打开后，Hexo将会在你每一次通过 hexo new [layout] <title> 命令创建新文章时自动创建一个文件夹。 这个资源文件夹将会有与这个文章文件一样的名字。 将所有与你的文章有关的资源放在这个关联文件夹中之后，你可以通过相对路径来引用它们，这样你就得到了一个更简单而且方便得多的工作流。

优劣如下：

  • ✅管理资源非常方便，便于后期对文章进行修改

  • ❌会有大量的文件夹

相对路径引用的标签插件

通过常规的 markdown 语法和相对路径来引用图片和其它资源可能会导致它们在存档页或者主页上显示不正确。 在Hexo 2时代，社区创建了很多插件来解决这个问题。 但是，随着Hexo 3 的发布，许多新的标签插件被加入到了核心代码中。 这使得你可以更简单地在文章中引用你的资源。

1
2
3
4
5
{% asset_path slug %}

{% asset_img slug [title] %}

{% asset_link slug [title] %}

比如说：当你打开文章资源文件夹功能后，你把一个 example.jpg 图片放在了你的资源文件夹中，如果通过使用相对路径的常规 markdown 语法 ![](example.jpg) ，它将 不会 出现在首页上。

正确的引用图片方式是使用下列的标签插件而不是 markdown ：

1
2
3
{% asset_img example.jpg This is an example image %}

{% asset_img "spaced asset.jpg" "spaced title" %}

通过这种方式，图片将会同时出现在文章和主页以及归档页中。

优劣如下：

  • ✅最稳定，不会因为其它插件冲突导致图片不显示

  • ❌操作复杂

  • ❌与其它 markdown 软件不兼容

使用 Markdown 嵌入图片

hexo-renderer-marked 3.1.0 引入了一个新的选项，其允许你无需使用 asset_img 标签插件就可以在 markdown 中嵌入图片

如需启用：

1
2
3
4
5
6
7
8
9
# _config.yml 配置

post_asset_folder: true

marked: 

  prependRoot: true

  postAsset: true

启用后，资源图片将会被自动解析为其对应文章的路径。 例如： image.jpg 位置为 /2020/01/02/foo/image.jpg ，这表示它是 /2020/01/02/foo/ 文章的一张资源图片， ![](image.jpg) 将会被解析为 <img src="/2020/01/02/foo/image.jpg"> 。

优劣如下：

  • ✅与 Obsidian 兼容

  • ❌依赖 hexo-renderer-marked 插件。如果需要 hexo-renderer-markdown-it，则必须删除该插件

  • ♻️替代方案：使用 hexo-asset-img 插件

博客配置

配置文件详解

注意：如果存在主题配置文件（如 _config.butterfly.yml），则其优先级高于 _config.yml。

这里解释 _config.yml 文件参数代表的含义，具体参考**官方文档**。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
# Hexo Configuration
## Docs: https://hexo.io/docs/configuration.html
## Source: https://github.com/hexojs/hexo/

# Site
title: Hexo        ## 网站标题
subtitle: ''       ## 网站副标题
description: ''    ## 网站描述
keywords:          ## 网站的关键词。 支持多个关键词。
author: John Doe   ## 网站所属者名字
language: en       ## 网站使用的语言。简体中文为 zh-CN
timezone: ''       ## 网站时区。默认为电脑的时区。中国大陆可以使用 Asia/Shanghai。

# URL
## Set your site url here. For example, if you use GitHub Page, set url as 'https://username.github.io/project'
url: http://example.com     ## 网站网址
root:                       ## 网站根目录。如果网站存放在子目录中，此处填子目录名
permalink: :year/:month/:day/:title/  ## 文章的永久链接格式
permalink_defaults:         ## 永久链接中各部分的默认值
pretty_urls:                ## 改写 permalink 的值来美化 URL
  trailing_index: true ## 是否在永久链接中保留尾部的 index.html，设置为 false 时去除
  trailing_html: true ## 是否在永久链接中保留尾部的 .html, 设置为 false 时去除 (对尾部的 index.html无效)

# Directory
source_dir: source         ## Source 文件夹 存储内容的位置
public_dir: public         ## Public 文件夹 生成静态站点的位置
tag_dir: tags              ## 标签文件夹
archive_dir: archives      ## 归档文件夹
category_dir: categories   ## 分类文件夹
code_dir: downloads/code   ## Include code 文件夹，source_dir 下的子目录
i18n_dir: :lang            ## 国际化（i18n）文件夹
skip_render:               ## 匹配到的文件将会被不做改动地复制到 public 目录中。 您可使用 glob 表达式来匹配路径。

# Writing
new_post_name: :title.md ## 新文章的文件名称
default_layout: post     ## 预设布局
titlecase: false         ## 把标题转换为 title case
external_link:
  enable: true           ## 在新标签中打开链接
  field: site            ## 对整个网站（site）生效或仅对文章（post）生效
  exclude: ''            ## 需要排除的域名。 主域名和子域名如 www 需分别配置
filename_case: 0         ## 设置为 1 ，将文件名转换为小写形式； 设置为 2 ，将文件名转换为大写形式。
render_drafts: false     ## 显示草稿
post_asset_folder: false ## 启用 资源文件夹
relative_link: false     ## 把链接改为与根目录的相对位址
future: true             ## 显示未来的文章
syntax_highlighter: highlight.js ## 代码块的设置,具体参考官方文档
highlight:
  line_number: true
  auto_detect: false
  tab_replace: ''
  wrap: true
  hljs: false
prismjs:
  preprocess: true
  line_number: true
  tab_replace: ''

# Home page setting
# path: Root path for your blogs index page. (default = '')
# per_page: Posts displayed per page. (0 = disable pagination)
# order_by: Posts order. (Order by date descending by default)
index_generator:        ## 生成帖子归档。由 hexo-generator-index 驱动。
  path: ''
  per_page: 10
  order_by: -date

# Category & Tag
default_category: uncategorized  ## 默认分类
category_map:                    ## 分类别名。参考官方文档。
tag_map:                         ## 标签别名。参考官方文档。

# Metadata elements
## https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta
meta_generator: true

# Date / Time format
## Hexo uses Moment.js to parse and display date
## You can customize the date format as defined in
## http://momentjs.com/docs/#/displaying/format/
date_format: YYYY-MM-DD     ## 日期格式
time_format: HH:mm:ss       ## 时间格式
## updated_option supports 'mtime', 'date', 'empty'
updated_option: 'mtime'     ## 当 Front Matter 中没有指定 updated 时 updated 的取值，默认为使用文件的最后修改时间。 

# Pagination
## Set per_page to 0 to disable pagination
per_page: 10             ## 每页显示的帖子数。 0 关闭分页功能
pagination_dir: page     ## URL format

# Include / Exclude file(s)
## 使用以下选项可明确处理或忽略某些文件/文件夹。 可以使用 glob 表达式 进行路径匹配。
## include 和 exclude 选项只会应用到 source/ ，而 ignore 选项会应用到所有文件夹。
## 具体参考官方文档
include:     ## 包含隐藏文件（包括名称以下划线开头的文件/文件夹，* 除外）
exclude:     ## 排除文件或文件夹
ignore:      ## 忽略文件/文件夹

# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
theme: landscape   ## 当前主题名称。 值为false时禁用主题
theme_config:      ## 主题的配置文件。 在这里放置的配置会覆盖主题目录下的 _config.yml 中的配置

# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:           ## 部署部分的设置
  type: ''

Hexo 命令列表

Hexo 命令参考官方文档。

其它 npm 命令：

1
npm list --depth 0     #列出 Hexo 已安装的所有插件

更改主题

注意：本文以 butterfly 主题为例，具体可参考官方的系列文章。

下载主题

1
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

应用主题

在 _config.yml 中，修改以下参数：

1
2
3
4
# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
theme: butterfly

安装插件

如果你没有 pug 以及 stylus 的渲染器，请下载安装：

1
npm install hexo-renderer-pug hexo-renderer-stylus --save

配置文件

将 \themes\butterfly\ 目录下的 _config.yml 复制一份到 Hexo 的根目录，并重命名为 _config.butterfly.yml。

在此配置文件里做出的修改，其优先级会高于根目录内的 _config.yml

升级主题

先将原文件夹重命名为别的名称，例如 butterfly-bkp，用于升级失败进行回退；

再重新执行安装命令：

1
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

比对升级后的配置文件_config.yml，如果某些配置发生了变化（改名或弃用），release 的说明里会特别提示或给出配置文件版本对比diff，同步修改原配置文件即可。

优化文章链接

注意：该插件会修改 permalink 参数，一些插件可能需要该参数，需注意兼容性问题。

安装 hexo-abbrlink 插件：

1
npm install hexo-abbrlink --save

修改 _config.yml 中的 permalink 参数：

1
2
3
permalink: posts/:abbrlink/ 
# 或者改成
permalink: posts/:abbrlink.html

在 _config.yml 中添加 hexo-abbrlink 插件的配置信息：

1
2
3
4
5
6
7
# abbrlink config
abbrlink:
  alg: crc32      # 用于计算 abbrlink 的算法。支持 crc16（默认）和 crc32
  rep: hex        # URL 中 abbrlink 的表示。支持 dec（默认）和 hex
  drafts: false   # 是否为草稿生成 abbrlink。（默认为 false）
  force: false    # 启用强制模式。在此模式下，插件将忽略缓存，并为每个帖子计算 abbrlink，即使它已经有 abbrlink。（默认为 false）
  writeback: true # 是否将对 front-matters 的更改写返回到实际的 markdown 文件。（默认为 true）

更换 Markdown 渲染器

注意：此插件似乎和 hexo-abbrlink 存在冲突，images相关参数不起作用。

参考资料：https://blog.csdn.net/qq_42951560/article/details/123596899

卸载 Hexo 自带的渲染器：

1
npm un hexo-renderer-marked --save

安装新的渲染器 hexo-renderer-markdown-it：

1
npm i hexo-renderer-markdown-it --save

将如下文本复制粘贴到 Hexo 的配置文件 _config.yml 的尾部：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
# hexo-renderer-markdown-it
## install date: 2024-2-19
## Docs: https://github.com/hexojs/hexo-renderer-markdown-it/?tab=readme-ov-file#options
markdown:
  preset: "default"
  render:
    html: true
    xhtmlOut: false
    langPrefix: "language-"
    breaks: true
    linkify: true
    typographer: true
    quotes: "“”‘’"
  enable_rules:
  disable_rules:
  plugins:
    - markdown-it-abbr
    - markdown-it-cjk-breaks
    - markdown-it-deflist
    - markdown-it-emoji
    - markdown-it-footnote
    - markdown-it-ins
    - markdown-it-mark
    - markdown-it-sub
    - markdown-it-sup
    - markdown-it-checkbox
    - markdown-it-imsize
    - markdown-it-expandable
    - name: markdown-it-container
      options: success
    - name: markdown-it-container
      options: tips
    - name: markdown-it-container
      options: warning
    - name: markdown-it-container
      options: danger
  anchors:
    level: 2
    collisionSuffix: ""
    permalink: false
    permalinkClass: "header-anchor"
    permalinkSide: "left"
    permalinkSymbol: "¶"
    case: 0
    separator: "-"
  images:
    lazyload: false
    prepend_root: false # Prepend root value to (internal) image path.
    post_asset: false # Resolve post asset's image path to relative path and prepend root value when post_asset_folder is enabled.

将 prepend_root 和 post_asset 的参数设为 true 之后，就可以使用标准 Markdown 语法插入图片。

其他优化

常见问题

无法插入图片

注意：使用相对路径后，最好不要再改动 markdown 文件对应的资源文件夹名称。

如果达成了以下要素：

  • 安装了 hexo-abbrlink 插件并修改了 permalink 参数

  • 删除了 hexo-renderer-marked 插件

  • 安装了 hexo-renderer-markdown-it 插件并添加了配置

  • _config.yml 中，参数 post_asset_folder: true

  • 使用 ![](image.jpg) 标准 markdown 语法来插入图片

此时使用 hexo g 生成后，图片路径为 http://localhost:4000/<文章标题>/image.jpg，这样找不到图片。推测是因为 hexo-abbrlink 插件和 hexo-renderer-markdown-it 插件不兼容。

做出如下修改：

  • 安装 hexo-asset-img 插件

  • 删除文章当前的 abbrlink，由插件重新生成。

使用 hexo clean 清理缓存后，hexo g 重新生成，再打开博客，图片正常显示。

npm 下载插件过程报错

错误信息：

1
2
3
4
5
6
7
8
9
npm ERR! code ETIMEDOUT
npm ERR! syscall connect
npm ERR! errno ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org/markdown-it-checkbox failed, reason: connect ETIMEDOUT 104.16.25.34:443
npm ERR! network This is a problem related to network connectivity.
npm ERR! network In most cases you are behind a proxy or have bad network settings.
npm ERR! network
npm ERR! network If you are behind a proxy, please make sure that the
npm ERR! network 'proxy' config is set properly.  See: 'npm help config'

更换 npm registry 地址：

1
npm config set registry https://registry.npmmirror.com

配置 Github 过程报错

错误信息：

1
2
3
4
5
Error: Spawn failed
    at ChildProcess.<anonymous> (D:\Blog\node_modules\hexo-util\lib\spawn.js:51:21)
    at ChildProcess.emit (node:events:513:28)
    at cp.emit (D:\Blog\node_modules\cross-spawn\lib\enoent.js:34:29)
    at ChildProcess._handle.onexit (node:internal/child_process:291:12)

将库的https链接改为 SSH 链接

或者删除 .deploy_git 文件夹重新生成

更改主题后无法正常进入主页

报错信息：

1
extends includes/layout.pug block content include ./includes/mixins/post-ui.pug #recent-posts.recent-posts +postUI include includes/pagination.pug

更换butterfly主题后，打开网页显示错误

漏下了主题安装教程中“安装插件”步骤

参考资料

https://hexo.io/zh-cn/docs/

https://zhuanlan.zhihu.com/p/26625249/

https://www.bilibili.com/video/BV1mU4y1j72n