Jekyll构建因Unknown tag 'macro'报错 转义后反斜杠显示异常

Jekyll 构建时会优先使用 Liquid 模板引擎解析所有页面、文章内容，{% %} 是 Liquid 原生的标签界定符，文章中写入的 Jinja2 宏代码 {% macro -%} 会被 Liquid 识别为自身标签，但 Liquid 没有内置 macro 标签，因此抛出语法错误。
反斜杠转义的方案无效，核心原因是反斜杠属于 Markdown 解析层的转义符，Liquid 解析优先级高于 Markdown 解析：反斜杠加在%前破坏了Liquid标签的{%开头匹配规则，所以能绕过Liquid语法校验，但后续Markdown解析时，反斜杠后跟随的%不属于Markdown支持的转义字符范围，反斜杠会被作为普通字符直接渲染到页面中。

方案1：使用Liquid原生raw标签包裹代码块（推荐） #

Liquid 提供了专门的 {% raw %} 标签，被该标签包裹的所有内容都会被Liquid直接跳过解析，不会识别任何模板语法，也不会输出多余字符，是这类场景的标准解法。
写Markdown内容时，只需要把需要展示的Jinja2代码块整体放在{% raw %}和{% endraw %}中间即可，示例写法：

{% raw %}
```jinja2
{% macro -%}

{% endraw %}

这种写法不会影响代码块的语法高亮，渲染后页面只会显示原始Jinja2代码，不会出现多余字符，也不会触发构建错误。

## 方案2：使用HTML实体编码替换特殊字符
如果是零散的行内代码片段，也可以把Liquid敏感的特殊字符替换为对应的HTML实体编码，让解析器无法识别为Liquid标签：
- `{` 替换为 `{`
- `%` 替换为 `%`
- `}` 替换为 `}`
比如示例代码片段可以写成 `{% macro -%}`，渲染后会正常显示为`{% macro -%}`。但这种写法可读性差、维护成本高，仅推荐用于短的行内内容。

---
内容的提问来源于stack exchange，提问作者Lanbao