解决al-folio项目中Liquid语法错误：Unknown tag 'toc'

在使用al-folio项目构建个人网站时，用户可能会遇到一个常见的构建错误："Liquid Exception: Liquid syntax error (line 60): Unknown tag 'toc' in /_layouts/post.liquid"。这个问题通常发生在部署阶段，而本地运行可能完全正常。

这个错误的核心原因是Jekyll的Liquid模板引擎无法识别'toc'标签。toc标签通常用于生成文章的目录(TOC, Table of Contents)，是jekyll-toc插件提供的功能。当GitHub Actions构建项目时，默认环境中可能没有安装这个必要的插件。

要解决这个问题，我们需要确保jekyll-toc插件在构建环境中可用。以下是具体解决方案：

1. 在项目的Gemfile中添加jekyll-toc依赖：

group :jekyll_plugins do
  gem 'jekyll-toc'
end

2. 在_config.yml配置文件中启用插件：

plugins:
  - jekyll-toc

3. 确保项目依赖已正确安装，可以运行：

bundle install

对于使用GitHub Pages部署的用户，需要注意GitHub Pages有特定的插件白名单。如果jekyll-toc不在白名单中，可以考虑以下替代方案：

1. 使用GitHub Actions进行构建和部署，而不是直接依赖GitHub Pages的自动构建
2. 在构建工作流中明确安装jekyll-toc插件
3. 或者考虑使用其他方法生成目录，如纯JavaScript方案

理解这个问题的本质很重要：它反映了Jekyll插件系统的工作方式。插件为Jekyll提供了扩展功能，但必须显式声明和安装。在开发环境和生产环境之间，插件可用性可能存在差异，这正是导致这个特定错误的原因。

通过正确配置项目依赖关系，可以确保构建系统能够识别和使用所有必要的Liquid标签，从而避免这类构建失败问题。