feat: group_by/group_by_exp/find/find_exp from Jekyll, #443

docs/source/zh-cn/tutorials/differences.md

@@ -29,10 +29,14 @@ LiquidJS 一直很重视兼容于 Ruby 版本的 Liquid。Liquid 模板语言最
 * 对象的迭代顺序。JavaScript 对象的迭代顺序是插入顺序和数字键递增顺序的组合，但 Ruby Hash 中只是插入顺序（JavaScript 字面量 Object 和 Ruby 字面量 Hash 的插入顺序解释也不同）。
 * 排序稳定性。shopify/liquid 和 LiquidJS 都没有定义 [sort][sort] 过滤器的稳定性在，它取决于 Ruby/JavaScript 内置的排序算法，在 Node.js 12+ 和 Google Chrome 70+ LiquidJS 的排序是 [稳定的][stable-sort]。
 * shopify/liquid 允许过滤器尾部的未匹配字符，但 LiquidJS 不允许。这就是说如果过滤器参数前忘记写冒号比如 `{%raw%}{{ "a b" | split " "}}{%endraw%}` LiquidJS 会抛出异常。这是为了提升 Liquid 模板的易用性，参考 [#208][#208] 和 [#212][#212]。
-* LiquidJS 有额外的标签：[layout][layout] 和相应的 `block`。
-* LiquidJS 有额外的过滤器：[json][json]。
+* LiquidJS 比 [Liquid 语言][liquid] 有更多的标签和过滤器：
+    * LiquidJS 自己定义的标签：[layout][layout]、[render][render] 和相应的 `block`。
+    * LiquidJS 自己定义的过滤器：[json][json]。
+    * 从 [Shopify][shopify-tags] 借来的不依赖 Shopify 平台的标签/过滤器。
+    * 从 [Jekyll][jekyll-filters] 借来的不依赖 Jekyll 框架的标签/过滤器。
 
-[layout]: https://liquidjs.com/tags/layout.html
+[layout]: ../tags/layout.html
+[render]: ../tags/render.html
 [json]: https://liquidjs.com/filters/json.html
 [#26]: https://github.com/harttle/liquidjs/pull/26
 [#59]: https://github.com/harttle/liquidjs/issues/59
@@ -46,3 +50,6 @@ LiquidJS 一直很重视兼容于 Ruby 版本的 Liquid。Liquid 模板语言最
 [plugins]: ./plugins.html#插件列表
 [ruby-liquid]: https://github.com/Shopify/liquid
 [afs]: https://liquidjs.com/tutorials/render-file.html#Abstract-File-System
+[liquid]: https://shopify.github.io/liquid/basics/introduction/
+[shopify-tags]: https://shopify.dev/docs/api/liquid/tags
+[jekyll-filters]: https://jekyllrb.com/docs/liquid/filters/

docs/source/zh-cn/tutorials/escaping.md

@@ -0,0 +1,76 @@
+---
+title: 转义
+---
+
+LiquidJS 种转义有两种含义：
+
+1. 输出语言的转义，即 HTML 转义。用来让输出的变量不包含 HTML 特殊字符，不影响 HTML 的结构，也就是输出 HTML 安全的字符串。
+2. 语言自己的转义，即 Liquid 转义。用来输出包含对于 Liquid 语言来说是特殊字符的字符串，比如你在使用 Liquid 模板语言来编写一篇介绍 Liquid 语法的文章时就会需要 Liquid 转义。
+
+## HTML 转义
+
+默认情况下输出是不转义的，但你可以用 [escape][escape] 过滤器来做 HTML 转义：
+
+输入
+```liquid
+{{ "1 < 2" | escape }}
+```
+
+输出
+```text
+1 &lt; 2
+```
+
+LiquidJS 也提供了其他过滤器来支持不同的转义需求：[escape_once][escape_once], [newline_to_br][newline_to_br], [strip_html][strip_html]。
+
+当输出的变量不被信任时，可以把 [outputEscape][outputEscape] 参数设置为 `"escape"` 来启用默认 HTML 转义。这种情况下，如果你需要某个输出不被转义，则需要使用 [raw][raw] 过滤器：
+
+输入
+```liquid
+{{ "1 < 2" }}
+{{ "<button>OK</button>" | raw }}
+```
+
+输出
+```text
+1 &lt; 2
+<button>OK</button>
+```
+
+## Liquid 转义
+
+为了输出 Liquid 的特殊字符比如 `{{` 和 `{%`，你需要 [raw][raw] 标签。
+
+输入
+```liquid
+{% raw %}
+  In LiquidJS, {{ this | escape }} will be HTML-escaped, but
+  {{{ that }}} will not.
+{% endraw %}
+```
+
+输出
+```text
+In LiquidJS, {{ this | escape }} will be HTML-escaped, but
+{{{ that }}} will not.
+```
+
+Within strings literals in LiquidJS template, `\` can be used to escape special characters in string syntax. For example:
+
+输入
+```liquid
+{{ "\"" }}
+```
+
+输出
+```liquid
+"
+```
+
+[outputEscape]: ./options.html#outputEscape
+[escape]: ../filters/escape.html
+[raw]: ../filters/raw.html
+[escape_once]: ../filters/escape.html
+[strip_html]: ../filters/strip_html.html
+[newline_to_br]: ../filters/newline_to_br.html
+[raw]: ../tags/raw.html

docs/source/zh-cn/tutorials/options.md

@@ -100,6 +100,14 @@ LiquidJS 把这个选项默认值设为 <code>true</code> 以兼容于 shopify/l
 
 例如，空字符串在 JavaScript 中为假（`jsTruthy` 为 `true` 时），在 Shopify 真值表中为真。
 
+## outputEscape
+
+[outputEscape][outputEscape] 用来自动转义输出。它的值可以是 `"escape"`、`"json"` 或 `(val: unknown) => string`，默认为 `undefined`。
+
+- 如果被输出的变量不被信任，可以设置 `outputEscape: "escape"` 来自动把它们 HTML 转义。如果要直接输出则需要使用 [raw][raw] 过滤器。
+- 如果你在用 LiquidJS 来生产 JSON 文件，可以设置为 `"json"`。
+- `outputEscape` 甚至可以是函数，你可以借此控制整个 LiquidJS 的变量输出。注意函数的输入不一定是字符串，因为过滤器的返回值可以不是字符串，你的函数将会接到这个值。
+
 ## 时间日期和时区
 
 **timezoneOffset** 用来指定一个和你当地时区不同的时区，所有日期和时间输出时都转换到这个指定的时区。例如设置 `timezoneOffset: 0` 将会把所有日期按照 UTC/GMT 00:00 来输出。
@@ -147,3 +155,5 @@ LiquidJS 把这个选项默认值设为 <code>true</code> 以兼容于 shopify/l
 [wc]: ./whitespace-control.html
 [intro]: ./intro-to-liquid.html
 [jekyllInclude]: /api/interfaces/LiquidOptions.html#jekyllInclude
+[raw]: ../filters/raw.html
+[outputEscape]: /api/interfaces/LiquidOptions.html#outputEscape