博客改版，起用Jekyll

2024-09-27 00:32

绕了一大圈，还是回到了Jekyll。

Github Pages本身自带Jekyll编译。我不用在本地安装Jekyll，只要按照规定的格式和网站结构来保存文章，Github会自动帮我编译渲染。

就是调试费点事，改动一点就提交到repo，刷新网页看看效果。还是因为我懒，不想安装什么Ruby什么的。虽然我也用过Ruby。

Jekyll会帮我做两件事：

  1. 从我的.md文件自动生成html页面。我原先自己手搓的md解析器完全没用了。
  2. 在任意html页面中支持Liquid模板语言，也就是说我可以在html里写下面这种代码：

<div id="blog-list" class="list-group">
    {% for post in site.posts limit: include.list_size %}
        {% assign mod = forloop.index | modulo: 2 %}
        {% if mod == 1 %}
        <a href="{{ post.url }}" class="list-group-item list-group-item-action list-group-item-primary">
        {% else %}
        <a href="{{ post.url }}" class="list-group-item list-group-item-action">
        {% endif %}
            <h6 class="mb-1">{{ post.title }}</h6>
            <small class="mb-1">{{ post.date | date: "%Y-%m-%d %H:%M" }}</small>
        </a>
    {% endfor %}
</div>

预先生成静态html的好处是加载很快。以前我的所有页面的导航条、博客页面的文章等都是javascript动态加载的，会有延迟。变成静态页面后就没有延迟的问题了。

Jekyll的md解析和我自己的相比，比较正规，支持的语法更多。但是它不支持有序列表从任意数字开始（我的支持），也没有办法定制化一些功能（我自己的想怎么玩就怎么玩）。我还挺想念我自己写的md解析器的。

除了可以从md生成文章页面，还可以生成功能更复杂的界面。现在我的导航条里那几个游戏、工具等二级主页都是从md文件生成的，md里面只提供下面这种结构化的数据，交给提供模板文件渲染就可以了。

---
layout: subindex

web-title:
  - lang: "en"
    content: "Games"
  - lang: "zh"
    content: "游戏"
...
catalogs:
  - id: "boardgames"
    title:
      - lang: "en"
        content: "Board Games"
      - lang: "zh"
        content: "棋类"
    items:
      - id: "gomoku"
        title:
          - lang: "en"
            content: "Gomoku"
          - lang: "zh"
            content: "五子棋"
        intro:
          - lang: "en"
            content: "15x15 board. Two-player game. No forbidden moves."
          - lang: "zh"
            content: "15x15 棋盘。双人游戏。黑方无禁手。"
        imageSrc: "/games/images/gomoku.png"
        src: "/games/gomoku.html"
...

数据结构也是我自己定义的。纯纯的前后端一把抓。

记录一下踩到的两个坑。

一、根据GitHub Pages的说法，只有在md和html文件的开头加上一个front matter，也就是类似下面这样用两个---夹起来的一些设置，这个页面才会被Jekyll处理。

---
layout: post
title: 又是Debug的一天
date: 2024-08-19 07:23:11
---

我在改版中把旧版博客也保留下来作为纪念，包括所有的md文件也留了一份未改动的。按说这些原版的md文件没有添加所谓的front matter，不应该被Jekyll处理。但是我看网站的构建log，发现还是生成了它们对应的静态html。

虽然多生成几个html页面也不影响，但我就觉得奇怪，四处搜了一下终于在StackOverflow上看到有人说是因为GitHub Pages用了一个Jekyll插件，给所有的md文件提供了一个默认的front matter。

真是多此一举，气得我。好在可以在设置中关掉这个插件。关掉之后那些旧版md文件就不会生成html了。

二、和上面相反，有几个html页面是添加了---之后也不被处理。

结果是，不光页面里的Liquid指令都失效了，要加载的内容加载不了了，只剩下Liquid语句赤裸裸地暴露在页面上；更糟糕的是，文件开头的---也保留下来了。浏览器看到一个html的开头不是<!DOCTYPE HTML>，而是---，于是它认为这个文件没有文档类型声明，没有<head> tag，一开始就是<body>正文。然后它就按这个意思开始展示页面……

这个问题也搜索了很久，终于在Jekyll的论坛上看到了真正原因。

原来是那几个html文件的最开头，添加了UTF-8 BOM。这是三个不显示的字符，在编辑器下看不到也删不了，但是Jekyll会识别出来然后认为文件不是以front matter开头的。

处理方法是，在VSCode下观察文件编码，会看到“UTF-8 with BOM”。点编码，选择按UTF-8保存文件，BOM就被删掉了。

找到答案之后再看Jekyll官网文档，原来文档里面已经大红色警告提醒你注意这个问题了。可是他的警告也说得不清不楚的，他说：

If you use UTF-8 encoding, make sure that no BOM header characters exist in your files or very, very bad things will happen to Jekyll. This is especially relevant if you’re running Jekyll on Windows.

我就算早一点看见也不会想到“very, very bad things”就是在说我遇到的这个问题。

最后，顺便把博客的编辑页面也升级了，加了很多按钮，成了一个功能相对完善的markdown编辑器。虽然其实只有我自己会用。

List