Jekyll博客搭建答疑解惑

Jekyll Blog Troubleshooting

# 核心问题

本篇期望使用简单的方法来帮助解决搭建Jekyll博客时遇到的种种问题,包括:

  1. Jekyll: command not found
  2. 从Blogger导入文章
  3. 使用highlight.js
  4. 使用fancybox
  5. 双线部署无法签发证书
  6. 用手机等其他局域网设备测试博客

希望你能借助这篇文章,少走些弯路。

# 前言

过去一直在Blogger自己写一些东西,但Blogger总有一些问题使得博客体验不佳:

  1. 主题太过单调,有些直男审美
  2. 落后的WYSIWYG编辑器,并且致命的是在HTML窗口编辑完切换回WYSIWYG窗口时,会自动将<p>替换为<div>,非常恼人
  3. 网络连接不佳
  4. 总有一种没有完全掌控的受害者心理作祟

由于上述原因,决定利用新安装的Manjaro环境的便利性,自己搭建一个博客。我一开始选择的是Hexo,虽然有诸多中文教程,但我发现似乎这一平台的活跃期已经过去;主题虽多,但多数已经年久失修;并且Hexo本身也不稳定,添加$PATH环境变量总是失败。在搭建尝试之后,发现喜欢的Hux Blog主题原版是Jekyll主题,进一步搜索资料发现Jekyll在国外比较活跃,又是GitHub钦定静态网站生成器,于是,便最终决定利用Jekyll+GitHub+Coding搭建一个双线Blog。

期间遇到非常多的问题,走了不少弯路,几乎把Google搜爆。在此,将问题做一个集合总结,建站的诸位可各取所需,绕坑而行。

如果需要完整建站教程,可以移步qiubaiyin的建站教程以及双线教程

# Command Not Found

在安装Jekyll的过程中,可能会遇到Command not found的问题,这是因为ruby文件夹没有被添加到全局变量,通过以下命令,将ruby路径添加到.bashrc可以解决。

首先编辑~/.bashrc

$ sudo nano .bashrc

在文件最后添加PATH=$PATH:~/.gem/ruby/2.7.0/bin,保存。

再运行:

$ source ~/.bashrc

即可将ruby添加到环境变量,顺利运行jekyll相关命令了。

# 从Blogger导入文章

既然是从Blogger迁移到Jekyll,首先要做的就是导入文章。

可以参考StackOverflow的帖子

# 从Blogger导出xml备份

首先,进入Blogger后台,侧边栏进入设置(Settings)-->其他(Other),点击备份(Back up Content),即可下载备份文件。

# 使用导入工具jekyll-import

随后,在Jekyll网站文件夹下建立一个*.rb文件。

然后编辑该文件,输入以下命令,将/path/to/blog-MM-DD-YYYY.xml修改为你的xml备份文件地址,并保存:

require "jekyll-import";
        JekyllImport::Importers::Blogger.run({
          "source"                => "/path/to/blog-MM-DD-YYYY.xml",
          "no-blogger-info"       => false, # not to leave blogger-URL info (id and old URL) in the front matter
          "replace-internal-link" => false, # replace internal links using the post_url liquid tag.
        })

在命令行中通过cd进入该文件夹,运行以下命令

$ gem install jekyll-import
$ ruby -rubygems nameoffile.rb

其中,nameoffile.rb为你刚才建立的.rb文件。

命令执行完成后,可以在_post文件夹中找到你导入的Blogger文章,文件格式为.html,由于jekyll兼容该格式,因此可以直接使用jekyll s命令查看效果。

# 调用Highlight.js

Jekyll3.0开始,已经内置了rouge代码高亮引擎,但似乎只能识别```标识的fenced code,由于jekyllmarkdown渲染器不能识别在HTML代码中的md代码,这就导致嵌入在<summary>中折叠的代码不能正确识别。

于是,决定重回Highlight.js的怀抱。调用的方式很简单,在_layouts/post.html中加入以下HTML代码即可,这里我是用的是Shades of Purple主题,可以依照喜好,根据官网demo修改。

<link rel="stylesheet"
      href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/styles/shades-of-purple.min.css">
<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/highlight.min.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

然后可以在_config.yml中禁用rouge

找到highlighter: rouge一行,将其修改为highlighter: none

找到kramdown:一行,在下方添加两行,如下

kramdown:
  ...
  syntax_highlighter_opts:
    disable: true
  ...

如此一来,便可以解决在HTML代码中不能代码高亮的问题了。

我使用的Hux Blog主题是没有自带的Lightbox的,不能放大查看图片,于是在GitHub上翻找,发现Fancybox颜值最高(颜值就是正义),于是便着手添加。

我的做法是直接在_includes/footer.html添加

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/fancyapps/fancybox@3.5.7/dist/jquery.fancybox.min.css" />
<script src="https://cdn.jsdelivr.net/gh/fancyapps/fancybox@3.5.7/dist/jquery.fancybox.min.js"></script>
<script>
$('[data-fancybox="gallery"]').fancybox({
  buttons : [
    'download',
    'thumbs',
    'close'
  ]
});
</script>

在编写文章时以<a href="path/to/original/img" data-fancybox="nameofgallery" data-caption="caption"><img src="path/to/thumbnail"></a>形式添加图片即可。

具体的Documentation请参阅Fancybox官网

# 双线部署 签发证书

参考Cote’s Blog

为了让自己的小伙伴访问博客的速度更快,我使用了GitHub+Coding的方式搭建博客,利用dnspod做分境内外的分别解析。在Coding申请证书时发现总是失败,最后通过暂停GitHub解析的方式成功申请了证书。

Pause GutHub DNS Resolution

Pause GitHub DNS Resolution, Screenshot from Cote’s Blog

在暂停GitHub解析后,Let’s Encrypt就可以正确访问博客,创建证书了。

# 用手机测试博客

在写博客的过程中,可能会遇到需要使用手机测试css/js的情景。如果直接使用jekyll s命令,发现在手机或者其他设备上上使用192.168.*.*:4000的局域网地址访问博客会提示Access Denied,这是因为Jekyll的服务器默认只在127.0.0.1:4000上开启。

这时,应当转而使用jekyll s --host=0.0.0.0

在服务器中,0.0.0.0指的是本机上的所有IPV4地址,如果一个主机有两个IP地址,192.168.1.1 和 10.1.2.1,并且该主机上的一个服务监听的地址是0.0.0.0,那么通过两个ip地址都能够访问该服务。

通过这条命令,使用localhost:4000或者192.168.*.*:4000就都能够访问博客测试了,解决了手机访问的问题。