fix: allow %Z for TimezoneDate, update docs accordingly #684

docs/source/filters/date.md

@@ -3,15 +3,15 @@ title: date
 ---
 {% since %}v1.9.1{% endsince %}
 
-# Format
-* Converts a timestamp into another date format
-* LiquidJS tries to be conformant with Shopify/Liquid which is using Ruby's core [Time#strftime(string)](http://www.ruby-doc.org/core/Time.html#method-i-strftime)
-  * Refer [format flags](https://ruby-doc.org/core/strftime_formatting_rdoc.html)
-  * Not all options are supported though - refer [differences here](/tutorials/differences.html#Differences)
-* The input is firstly converted to `Date` object via [new Date()][jsDate]
-* Date format can be provided individually as a filter option
-    * If not provided, then `%A, %B %-e, %Y at %-l:%M %P %z` format will be used as default format
-    * Override this using [`dateFormat`](/api/interfaces/LiquidOptions.html#dateFormat) LiquidJS option, to set your preferred default format for all date filters
+Date filter is used to convert a timestamp into the specified format.
+
+* LiquidJS tries to conform to Shopify/Liquid, which uses Ruby's core [Time#strftime(string)](http://www.ruby-doc.org/core/Time.html#method-i-strftime). There're differences with [Ruby's format flags](https://ruby-doc.org/core/strftime_formatting_rdoc.html):
+  * `%Z` (since v10.11.1) works when there's a passed-in timezone name from `LiquidOption` or in-place value (see TimeZone below). If passed-in timezone is an offset number instead of string, it'll behave like `%z`. If there's none passed-in timezone, it returns [the runtime's default time zone](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/resolvedOptions#timezone).
+  * LiquidJS provides an additional `%q` flag for date ordinals. e.g. `{{ '2023/02/02' | date: '%d%q of %b'}}` => `02nd of Feb`
+* Date literals are firstly converted to `Date` object via [new Date()][jsDate], that means literal values are considered in runtime's time zone by default.
+* The format filter argument is optional:
+    * If not provided, it defaults to `%A, %B %-e, %Y at %-l:%M %P %z`.
+    * The above default can be overridden by [`dateFormat`](/api/interfaces/LiquidOptions.html#dateFormat) LiquidJS option.
 
 ### Examples
 ```liquid
@@ -23,16 +23,14 @@ title: date
 ```
 
 # TimeZone
-* By default, dates will be converted to local timezone before output
-* You can override that by,
-    * setting a timezone for each individual `date` filter via the second parameter
-    * using the [`timezoneOffset`](/api/interfaces/LiquidOptions.html#timezoneOffset) LiquidJS option
-        * Its default value is your local timezone offset which can be obtained by `new Date().getTimezoneOffset()`
+* During output, LiquidJS uses local timezone which can override by:
+    * setting a timezone in-place when calling `date` filter, or
+    * setting the [`timezoneOffset`](/api/interfaces/LiquidOptions.html#timezoneOffset) LiquidJS option
+        * It defaults to runtime's time one.
         * Offset can be set as,
             * minutes: `-360` means `'+06:00'` and `360` means `'-06:00'`
             * timeZone ID: `Asia/Colombo` or `America/New_York`
-        * Use minutes for better performance with repeated processing of templates with many dates like, converting template for each email recipient
-    * Refer [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for TZ database values
+    * See [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for TZ database values
 
 ### Examples
 ```liquid
@@ -41,7 +39,6 @@ title: date
 {{ "1990-12-31T23:00:00Z" | date: "%Y-%m-%dT%H:%M:%S", "Asia/Colombo" }} => 1991-01-01T04:30:00
 ```
 
-
 # Input
 * `date` works on strings if they contain well-formatted dates
 * Note that LiquidJS is using [JavaScript Date][jsDate] to parse the input string, that means [IETF-compliant RFC 2822 timestamps](https://datatracker.ietf.org/doc/html/rfc2822#page-14) and strings in [a version of ISO8601](https://www.ecma-international.org/ecma-262/11.0/#sec-date.parse) are supported.

docs/source/tutorials/differences.md

@@ -33,8 +33,8 @@ Though we're trying to be compatible with the Ruby version, there are still some
     * 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`
+    * Tags/filters that don't depend on Jekyll framework are borrowed from [Jekyll][jekyll-filters].
+* Some tags/filters behave differently: [date][date] filter.
 
 [date]: https://liquidjs.com/filters/date.html
 [layout]: ../tags/layout.html

docs/source/zh-cn/filters/date.md

@@ -6,6 +6,14 @@ title: date
 
 把时间戳转换为字符串。LiquidJS 尝试跟 Shopify/Liquid 保持一致，它用的是 Ruby 核心的 [Time#strftime(string)](http://www.ruby-doc.org/core/Time.html#method-i-strftime)。此外 LiquidJS 会先通过 [new Date()][newDate] 尝试把输入转换为 Date 对象。
 
+但 LiquidJS 支持的格式与 [Ruby 的 flag](https://ruby-doc.org/core/strftime_formatting_rdoc.html) 有些不同：
+  * `%Z`（自 v10.11.1 起支持）只有在传入了时区时才起作用（可以通过 `LiquidOption` 传入，也可以在创建日期时单独传入，见下文）。如果传入的时区是个数字，那么它的表现将会与 `%z` 相同。如果没有传入时区，将会返回 [运行时默认时区](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/resolvedOptions#timezone)。
+  * LiquidJS 提供额外的 `%q` 用来处理序数：`{{ '2023/02/02' | date: '%d%q of %b'}}` => `02nd of Feb`
+* 日期字面量会通过 [new Date()][jsDate] 转化为 `Date` 对象，这意味着字面量默认使用运行时默认时区。
+* 格式字参数是可选的：
+    * 如果不传，默认为 `%A, %B %-e, %Y at %-l:%M %P %z`。
+    * 上述默认值可以通过 [`dateFormat`](/api/interfaces/LiquidOptions.html#dateFormat) 参数覆盖。
+
 输入
 ```liquid
 {{ article.published_at | date: "%a, %b %d, %y" }}

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

@@ -34,6 +34,7 @@ LiquidJS 一直很重视兼容于 Ruby 版本的 Liquid。Liquid 模板语言最
     * LiquidJS 自己定义的过滤器：[json][json]。
     * 从 [Shopify][shopify-tags] 借来的不依赖 Shopify 平台的标签/过滤器。
     * 从 [Jekyll][jekyll-filters] 借来的不依赖 Jekyll 框架的标签/过滤器。
+* 有些过滤器和标签表现不同：比如 [date][date]。
 
 [layout]: ../tags/layout.html
 [render]: ../tags/render.html