前言

世界上除了学不完的知识,还有排不完的bug。。

本篇记录自己在使用butterfly主题时遇到的各种报错,每个都是独一无二且千奇百怪的

排除bug是一个非常折腾+耗时间的过程,或许本文会一直更新下去吧~(恼)

1. YAMLException: bad indentation of a mapping entry

1
2
3
4
5
6
7
8
9
10
11
12
13
# 运行hexo g后出现如下报错
YAMLException: bad indentation of a mapping entry (7:20)

4 |
5 | menu:
6 | 首页:/ || fas fa-home
7 | 菜单 || fas fa-list:
------------------------^
8 | 时间轴: /archives/ || fas fa-archive
9 | 标签: /tags/ || fas fa-tags
at generateError (D:\Blog\悠悠の哉\node_modules\js-yaml\lib\loader.js:183:10)
at throwError (D:\Blog\悠悠の哉\node_modules\js-yaml\lib\loader.js:187:9)
...
1
2
报错原因:一般是英文冒号后缺失空格
解决方法:通过报错找到相应位置,添加空格

这或许是目前遇到的最多的报错了吧。。

2. warning: adding embedded git repository: XXXX

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 运行git add .后出现如下报错
warning: adding embedded git repository:xxxxxxxxxx
hint: You've added another git repository inside your current repository.
hint: Clones of the outer repository will not contain the contents of
hint: the embedded repository and will not know how to obtain it.
hint: If you meant to add a submodule, use:
hint:
hint: git submodule add <url>xxxxxxxxxx
hint:
hint: If you added this path by mistake, you can remove it from the
hint: index with:
hint:
hint: git rm --cached xxxx
hint:
hint: See "git help submodule" for more information.
1
2
3
4
5
6
7
8
9
10
11
12
13
报错原因:没有添加相应的子模块,在.gitmodules中没有这个子模块的path和url信息。
经常出现在配置完主题,却没有添加子模块的情况。
解决方法:以主题`butterfly`为例,运行如下指令:
# 如果是文件
git rm --cached themes/butterfly
# 如果执行以上命令后若提示:【 error: 如下文件其暂存的内容和工作区及 HEAD 中的都不一样:】 ,`-f`强制删除
git rm -f --cached themes/butterfly

#=添加仓库索引=======================================
# 创建子模块并添加butterfly的url地址
# 格式为git submodule add <url> <path>
git submodule add https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly
# 或者也可以使用butterfly的ssh地址

3. github报错Jekyll::Errors::MissingDependencyException和Gem::MissingSpecError

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
#配置完butterfly主题,在将本地博客文件push到github上后,显示如下错误:
/usr/local/bundle/gems/jekyll-3.9.2/lib/jekyll/theme.rb:84:in `rescue in gemspec': The butterfly theme could not be found. (Jekyll::Errors::MissingDependencyException)
from /usr/local/bundle/gems/jekyll-3.9.2/lib/jekyll/theme.rb:81:in `gemspec'
from /usr/local/bundle/gems/jekyll-3.9.2/lib/jekyll/theme.rb:19:in `root'
from /usr/local/bundle/gems/jekyll-3.9.2/lib/jekyll/theme.rb:12:in `initialize'
......
/usr/local/lib/ruby/2.7.0/rubygems/dependency.rb:311:in `to_specs': Could not find 'butterfly' (>= 0) among 148 total gem(s) (Gem::MissingSpecError)
Checked in 'GEM_PATH=/github/home/.gem/ruby/2.7.0:/usr/local/lib/ruby/gems/2.7.0:/usr/local/bundle', execute `gem env` for more information
from /usr/local/lib/ruby/2.7.0/rubygems/dependency.rb:323:in `to_spec'
from /usr/local/lib/ruby/2.7.0/rubygems/specification.rb:986:in `find_by_name'
from /usr/local/bundle/gems/jekyll-3.9.2/lib/jekyll/theme.rb:82:in `gemspec'
......
Logging at level: debug
Configuration file: /github/workspace/./_config.yml
Theme: butterfly
github-pages 227 | Error: The butterfly theme could not be found.
1
2
原因:尚未清楚出现这个报错的原因。
由于这一步出现在github page build and deploy,因此初步判断是,github无法根据仓库内容构建和部署github page导致的正常报错,而我没有将网站部署在github page的想法,对于后续Netlify网站的部署也没有任何影响,因此目前对这个报错可以忽略不管。

4. YAMLException: duplicated mapping key

1
2
3
4
5
6
7
8
9
10
# 输入hexo g后,出现如下报错:
YAMLException: duplicated mapping key (16:1)

13 | keywords: Butterfly, hexo
14 | top_image:
15 | cover:
16 | highlight_shrink: false
------^
at generateError (D:\Blog\悠悠の哉\node_modules\js-yaml\lib\loader.js:183:10)
......
1
Front内容出现了重复,需要将重复内容删除

5. 文章目录无法跳转

点击文章页一级目录无反应,但二级目录可以正常跳转。打开浏览器右键菜单,点击“检查-控制台”查看html,发现点击目录一级标题后会出现如下报错:

1
2
3
Uncaught TypeError: Cannot read properties of null (reading 'offsetTop')
at Object.getEleTop (utils.js:208:25)
at HTMLDivElement.<anonymous> (main.js:369:30)

image-20220921014231760

检查“页面元素”,发现目录一级标题的'toc-link'后没有正常生成href属性,因此无法实现跳转。

image-20220921014914595

出现此问题的原因是markdown-it插件的 bug,butterfly主题的博客是由markdown-it渲染的,而这个插件并未渲染 heading 的 id 所以导致锚点失效,目录无法正常跳转。

解决方法是首先安装 markdown-it-named-headings 插件:

1
npm install markdown-it-named-headings --save

然后进入项目的根目录,修改根目录下 node_modules\hexo-renderer-markdown-it\lib\renderer.js 文件,在 renderer.js 中添加一行以使用此插件:

1
parser.use(require('markdown-it-named-headings'))

可能需要根据该文件中具体的代码格式进行适当修改

我的修改效果如下:

修改js文件

记得保存修改,重新运行后即可正常实现目录一级标题的跳转。

详细问题描述及解决方案参考Hexo 博客踩坑 | blog (convivae.top)