目录

Hugo系列(4) - 从Hexo迁移至Hugo以及使用LoveIt主题的踩坑记录

前言

本文主要记录从Hexo迁移至Hugo所遇到的一些坑,以及Hugo的LoveIt主题的一些bug之类的应对方案。下面是涉及到的Hexo、Hugo以及LoveIt各自的版本:

1
2
3
4
5
hexo: 3.8.0

hugo: v0.74.2-48565DE6 windows/amd64 BuildDate: 2020-07-17T17:22:50Z

LoveIt: v0.2.10

Hugo无法使用abbrlink导致的URL与原本Hexo的URL不同步

原本的Hexo博客使用了hexo-abbrlink插件,目的是为每篇文章生成由字母和数字组成的随机URL,这样有利于SEO。迁移到Hugo后没找到类似的插件,只能用自带的slug功能来代替。

原本的文章文件头里有一个abbrlink属性,如下:

1
2
3
---
abbrlink: 71bd19d3
---

为了让旧的文章url和以前保存一致,于是全部加上一个slug属性,如下:

1
2
3
4
---
abbrlink: 71bd19d3
slug: 71bd19d3
---

然后在站点配置文件里这样配置:

1
2
[permalinks]
  posts = "/posts/:slug.html"

这样就可以避免旧文章的URL在迁移后不一致的问题,但是这也引入了另一个问题,那就是每一篇新文章都要手动添加slug属性,否则就还是会直接拿文章标题来作为URL的一部分。

不过这点还是可以接受的,每篇文章额外配置slug也不算麻烦,毕竟博客园同样有提供这种给URL起别名的功能,可以把一系列的文章起一些比较接近的URL,更有利于访问。

Valine评论功能无法使用

LoveIt主题的评论功能默认情况下是无法在本地使用的,除非修改模板渲染文件,或者启动本地服务时添加参数,如下:

1
hugo server -e production

这样就可以在本地调试时使用"评论系统”, “CDN” 和 “fingerprint”。

但是对于v0.2.10版本的LoveIt主题,只是加入启动参数依然无法使用Valine评论功能,原因是评论功能的模板文件有问题,需要我们自己修改才能正常使用,如下:

  1. \themes\LoveIt\layouts\partials\comment.html拷贝到站点根目录下的\layouts\partials\comment.html
  2. 打开拷贝后的comment.html,找到Valine相关的代码,把{{- if $valine.enable -}}{{- end -}}之间的代码改成如下:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{{- if $valine.enable -}}
    <div id="valine" class="comment"></div>
    <script src="//cdn1.lncld.net/static/js/3.0.4/av-min.js"></script>
	<script src='/js/Valine.min.js'></script>

	<script type="text/javascript">
		new Valine({
			el: '#valine' ,
			appId: '{{ $valine.appId }}',
			appKey: '{{ $valine.appKey }}',
			notify: '{{ $valine.notify }}', 
			verify: '{{ $valine.verify }}', 
			avatar:'{{ $valine.avatar }}', 
			placeholder: '{{ $valine.placeholder }}',
			visitor: '{{ $valine.visitor }}'
		});
	</script>
{{- end -}}

之后在站点配置文件里启用valine,然后填上从LeanCloud的应用中得到的appIdappKey就可以用了。并且在使用了valine的同时,还可以顺带启用阅读次数的统计功能。以前用Hexo的时候,就是用的LeanCloud来帮忙统计阅读次数的。

LeanCloud的使用也很简单,去官网注册个账号,然后创建一个应用,然后进入该应用的配置,选择设置 -> 应用Keys,然后复制该应用的appIdappKey到站点配置文件里就行了。

lightgallery图片相册功能无法使用

在启用了lightgallery功能后无法触发,然后在LoveIt仓库里找到了类似的issue,发现必须使用带标题的图片才能使用相册功能,如下:

1
![Alt Text](/url/to/your/image "Title")

但是一般情况下在引入图片时都不会再特地起一个标题,尤其是原本就已经有大量文章里使用了不带标题的图片,想全部改过来是不可能的。

接着发现已经有人发起了PR修复了该issue,只是作者还没merge,所以只能把这段代码自行合并到自己的博客项目了。做法也很简单:

  • 在站点根目录下创建的/layouts/_default/_markup/render-image.html
  • 在新创建的这个render-image.html文件里黏贴下面的代码即可:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{{ $figcap := or .Title .Text }}
{{ $caption := or .Text " " }}
{{- if eq $figcap $caption -}}
    {{ $caption = " " }}
{{- end -}}

{{- if $figcap -}}
    <figure>
        {{- dict "Src" .Destination "Title" $figcap "Caption" $caption "Linked" true "Resources" .Page.Resources | partial "plugin/image.html" -}}
        <figcaption class="image-caption">
            {{- $figcap | safeHTML -}}
        </figcaption>
    </figure>
{{- else -}}
    {{- dict "Src" .Destination "Title" (path.Base .Destination) "Resources" .Page.Resources | partial "plugin/image.html" -}}
{{- end -}}

无法直接自定义CSS和JavaScript

LoveIt没有直接提供自定义JavaScript的文件,CSS倒是有提供\themes\LoveIt\assets\css\_custom.scss,但是经过测试并无法生效。

最终决定修改页面的模板文件来引入自定义的CSS和JavaScript文件,具体做法可以参考Hugo系列(6) - LoveIt主题美化:添加自定义CSS和JavaScript

文章摘要标志不生效

和Hexo不同,Hugo的文章摘要标志必须是<!--more-->,在more的两边不能有任何空格,且必须全小写,否则便不会生效。用法如下:

1
2
3
4
## Title

Content.
<!--more-->

文章标题里的特殊符号不需要使用实体字符

在Hexo里,如果文章的标题里存在英文的双引号、冒号等特定的符号,必须使用实体字符来替代,否则就会报错。而在Hugo里,则没有这个需要,直接使用原本的符号就行。如果在标题里使用实体字符,并不会被自动解析成对应的字符。

Console报错找不到/site.webmanifest

不管是本地调试,还是远程部署,始终都会在浏览器的Console里报这个错,网上也没找到相关的说法,也不知道这个文件的具体作用。

最终还是决定把这个引用给去掉,做法如下:

  • 把博客主题目录下的\themes\LoveIt\layouts\partials\head\link.html拷贝到根目录下的\layouts\partials\head\link.html
  • 打开拷贝后的link.html,把<link rel="manifest" href="/site.webmanifest">删掉或者注释掉:
1
{{- /*    <link rel="manifest" href="/site.webmanifest"> */ -}}

远程部署到GitHub Pages后build失败

在本地调试没问题,部署到Coding Pages也没问题,偏偏部署到GitHub Pages 就一直build失败,并一直发送邮件,可以从邮件里看到报错的原因,如下:

1
2
3
4
5
6
7
8
9
The page build failed for the `master` branch with the following error:

Page build failed. For more information, see https://docs.github.com/github/working-with-github-pages/troubleshooting-jekyll-build-errors-for-github-pages-sites#troubleshooting-build-errors.

For information on troubleshooting Jekyll see:

  https://docs.github.com/articles/troubleshooting-jekyll-builds

If you have any questions you can submit a request on the Contact GitHub page at https://support.github.com/contact?repo_id=130235157&page_build_id=208464262

可以看到报错说是Page build failed.,描述太过模糊不清,我只能一篇篇文章的排查测试。最终发现,问题出在了某篇文章里的代码块,如下:

1
2
3
4
5
6
<body>
  ....

  {% include '_custom/custom-foot.swig' %}
</body>
</html>

问题就出在了这个{% %}上,经过几番测试,发现一旦启用了LoveIt主题的Markdown输出功能(即将每篇文章link到原本的Markdown文件),就会造成GitHub Pages服务build失败。

最佳的解决方案就是禁用Markdown输出功能,站点配置文件如下:

 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
[params]
  [params.page]
    # whether to show link to Raw Markdown content of the content
    # 是否显示原始 Markdown 文档内容的链接
    linkToMarkdown = false

# Options to make output .md files
# 用于输出 Markdown 格式文档的设置
#[mediaTypes]
#  [mediaTypes."text/plain"]
#    suffixes = ["md"]

# Options to make output .md files
# 用于输出 Markdown 格式文档的设置
#[outputFormats.MarkDown]
#  mediaType = "text/plain"
#  isPlainText = true
#  isHTML = false

# Options to make hugo output files
# 用于 Hugo 输出文档的设置
[outputs]
  home = ["HTML", "RSS", "JSON"]
#  page = ["HTML", "MarkDown"]
  page = ["HTML"]
  section = ["HTML", "RSS"]
  taxonomy = ["HTML", "RSS"]
  taxonomyTerm = ["HTML"]

在站点配置文件了将linkToMarkdown配置为false,并将对应的三项Markdown输出的属性注释掉,终于解决了GitHub Pages编译失败的问题。

参考链接