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

docs/source/tutorials/differences.md

@@ -16,7 +16,7 @@ In the meantime, it's now implemented in JavaScript, that means it has to be mor
 * **Async as first-class citizen**. Filters and tags can be implemented asynchronously by return a `Promise`.
 * **Also can be sync**. For scenarios that are not I/O intensive, render synchronously can be much faster. You can call synchronous APIs like `.renderSync()` as long as all the filters and tags in template support to be rendered synchronously. All builtin filters/tags support both sync and async render.
 * **[Abstract file system][afs]**. Along with async feature, LiquidJS can be used to serve templates stored in Databases [#414][#414], on remote HTTP server [#485][#485], and so on.
-* **Additional tags and filters** like `layout` and `json`.
+* **Additional tags and filters** like `layout` and `json`, see below for details.
 
 ## Differences
 
@@ -29,11 +29,16 @@ Though we're trying to be compatible with the Ruby version, there are still some
 * Iteration order for objects. The iteration order of JavaScript objects, and thus LiquidJS objects, is a combination of the insertion order for string keys, and ascending order for number-like keys, while the iteration order of Ruby Hash is simply the insertion order.
 * Sort stability. The [sort][sort] stability is also not defined in both shopify/liquid and LiquidJS, but it's [considered stable][stable-sort] for LiquidJS in Node.js 12+ and Google Chrome 70+.
 * Trailing unmatched characters inside filters are allowed in shopify/liquid but not in LiquidJS. It means filter arguments without a colon like `{%raw%}{{ "a b" | split " "}}{%endraw%}` will throw an error in LiquidJS. This is intended to improve Liquid usability, see [#208][#208] and [#212][#212].
-* LiquidJS has additional tags: [layout][layout] and corresponding `block` tag.
+* LiquidJS has more tags/filters than [the Liquid language][liquid]:
+    * LiquidJS-defined tags: [layout][layout], [render][render] and corresponding `block` tag.
+    * LiquidJS-defined filters: [json][json].
+    * Tags/filters that don't depend on Shopify platform are borrowed from [Shopify][shopify-tags].
+    * Tags/filters that don't depend on Jekyll framework are borrowed from [Jekyll][jekyll-filters]
 * LiquidJS [date][date] filter supports `%q` for date ordinals like `{{ '2023/02/02' | date: '%d%q of %b'}}` => `02nd of Feb`
 
 [date]: https://liquidjs.com/filters/date.html
-[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
@@ -47,3 +52,6 @@ Though we're trying to be compatible with the Ruby version, there are still some
 [plugins]: ./plugins.html#Plugin-List
 [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/tutorials/escaping.md

@@ -0,0 +1,76 @@
+---
+title: Escaping
+---
+
+Escaping is important in all languages, including LiquidJS. While escaping has 2 different meanings for a template engine:
+
+1. Escaping for the output, i.e. HTML escape. Used to escape HTML special characters so the output will not break HTML structures, aka HTML safe.
+2. Escaping for the language itself, i.e. Liquid escape. Used to output strings that's considered special in Liquid language. This will be useful when you're writing an article in Liquid template to introduce Liquid language.
+
+## HTML Escape
+
+By default output is not escaped. While you can use [escape][escape] filter for this:
+
+Input
+```liquid
+{{ "1 < 2" | escape }}
+```
+
+Output
+```text
+1 &lt; 2
+```
+
+There's also [escape_once][escape_once], [newline_to_br][newline_to_br], [strip_html][strip_html] filters for you to fine tune your output.
+
+In cases where variables are mostly not trusted, [outputEscape][outputEscape] can be set to `"escape"` to apply escape by default. In this case, when you need some output not to be escaped, [raw][raw] filter can be used:
+
+Input
+```liquid
+{{ "1 < 2" }}
+{{ "<button>OK</button>" | raw }}
+```
+
+Output
+```text
+1 &lt; 2
+<button>OK</button>
+```
+
+## Liquid Escape
+
+To disable Liquid language and output strings like `{{` and `{%`, the [raw][raw] tag can be used.
+
+Input
+```liquid
+{% raw %}
+  In LiquidJS, {{ this | escape }} will be HTML-escaped, but
+  {{{ that }}} will not.
+{% endraw %}
+```
+
+Output
+```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:
+
+Input
+```liquid
+{{ "\"" }}
+```
+
+Output
+```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/tutorials/options.md

@@ -102,6 +102,14 @@ Before 2.0.1, <code>extname</code> is set to `.liquid` by default. To change tha
 
 it defaults to false.  For example, when set to true, a blank string would evaluate to false with jsTruthy. With Shopify's truthiness, a blank string is true.
 
+## outputEscape
+
+[outputEscape][outputEscape] can be used to automatically escape output strings. It can be one of `"escape"`, `"json"`, or `(val: unknown) => string`, defaults to `undefined`.
+
+- For untrusted output variables, set `outputEscape: "escape"` makes them be HTML escaped by default. You'll need [raw][raw] filter for direct output.
+- `"json"` is useful when you're using LiquidJS to create valid JSON files.
+- It can even be a function which allows you to control what variables are output throughout LiquidJS. Please note the input can be any type other than string, e.g. an filter returned an non-string value.
+
 ## Date
 
 **timezoneOffset** is used to specify a different timezone to output dates, your local timezone will be used if not specified. For example, set `timezoneOffset: 0` to output all dates in UTC/GMT 00:00.
@@ -151,3 +159,5 @@ Parameter orders are ignored by default, for ea `{% for i in (1..8) reversed lim
 [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