docs: website for LiquidJS

2026-09-20 06:50:47 -07:00 · 2020-03-28 17:21:07 +08:00
parent 0633dbeabb
commit 3e42d6b1b0
422 changed files with 14509 additions and 50335 deletions
@@ -0,0 +1,37 @@
+---
+title: abs
+---
+
+返回数字的绝对值。
+
+输入
+```liquid
+{{ -17 | abs }}
+```
+
+输出
+```text
+17
+```
+
+输入
+```liquid
+{{ 4 | abs }}
+```
+
+输出
+```text
+4
+```
+
+对于只包含数字的字符串也好使：
+
+输入
+```liquid
+{{ "-19.86" | abs }}
+```
+
+输出
+```text
+19.86
+```
@@ -0,0 +1,29 @@
+---
+title: append
+---
+
+连接两个字符串并返回结果。
+
+输入
+```liquid
+{{ "/my/fancy/url" | append: ".html" }}
+```
+
+输出
+```text
+/my/fancy/url.html
+```
+
+也可以用于变量。
+
+输入
+```liquid
+{% assign filename = "/index.html" %}
+{{ "website.com" | append: filename }}
+```
+
+输出
+```text
+
+website.com/index.html
+```
@@ -0,0 +1,25 @@
+---
+title: at_least
+---
+
+限制数字到某个最小值。
+
+输入
+```liquid
+{{ 4 | at_least: 5 }}
+```
+
+输出
+```text
+5
+```
+
+输入
+```liquid
+{{ 4 | at_least: 3 }}
+```
+
+输出
+```text
+4
+```
@@ -0,0 +1,25 @@
+---
+title: at_most
+---
+
+限制数字到某个最大值。
+
+输入
+```liquid
+{{ 4 | at_most: 5 }}
+```
+
+输出
+```text
+4
+```
+
+输入
+```liquid
+{{ 4 | at_most: 3 }}
+```
+
+输出
+```text
+3
+```
@@ -0,0 +1,27 @@
+---
+title: capitalize
+---
+
+把字符串首字母改为大写。
+
+输入
+```liquid
+{{ "title" | capitalize }}
+```
+
+输出
+```text
+Title
+```
+
+`capitalize` 只会大写首字母，因此后续单词的不会受影响：
+
+ Input
+```liquid
+{{ "my great title" | capitalize }}
+```
+
+输出
+```text
+My great title
+```
@@ -0,0 +1,47 @@
+---
+title: ceil
+---
+
+向上取整，取整前 LiquidJS 会首先把输入转换为数字。
+
+输入
+```liquid
+{{ 1.2 | ceil }}
+```
+
+输出
+```text
+2
+```
+
+输入
+```liquid
+{{ 2.0 | ceil }}
+```
+
+输出
+```text
+2
+```
+
+输入
+```liquid
+{{ 183.357 | ceil }}
+```
+
+输出
+```text
+184
+```
+
+下面的例子中输入是字符串：
+
+输入
+```liquid
+{{ "3.5" | ceil }}
+```
+
+输出
+```text
+4
+```
@@ -0,0 +1,47 @@
+---
+title: compact
+---
+
+Removes any `nil` values from an array.
+
+For this example, assume `site.pages` is an array of content pages for a website, and some of these pages have an attribute called `category` that specifies their content category. If we `map` those categories to an array, some of the array items might be `nil` if any pages do not have a `category` attribute.
+
+输入
+```liquid
+{% assign site_categories = site.pages | map: "category" %}
+
+{% for category in site_categories %}
+- {{ category }}
+{% endfor %}
+```
+
+输出
+```text
+- business
+- celebrities
+-
+- lifestyle
+- sports
+-
+- technology
+```
+
+By using `compact` when we create our `site_categories` array, we can remove all the `nil` values in the array.
+
+输入
+```liquid
+{% assign site_categories = site.pages | map: "category" | compact %}
+
+{% for category in site_categories %}
+- {{ category }}
+{% endfor %}
+```
+
+输出
+```text
+- business
+- celebrities
+- lifestyle
+- sports
+- technology
+```
@@ -0,0 +1,53 @@
+---
+title: concat
+---
+
+Concatenates (joins together) multiple arrays. The resulting array contains all the items from the input arrays.
+
+输入
+```liquid
+{% assign fruits = "apples, oranges, peaches" | split: ", " %}
+{% assign vegetables = "carrots, turnips, potatoes" | split: ", " %}
+
+{% assign everything = fruits | concat: vegetables %}
+
+{% for item in everything %}
+- {{ item }}
+{% endfor %}
+```
+
+输出
+```text
+- apples
+- oranges
+- peaches
+- carrots
+- turnips
+- potatoes
+```
+
+You can string together `concat` filters to join more than two arrays:
+
+输入
+```liquid
+{% assign furniture = "chairs, tables, shelves" | split: ", " %}
+
+{% assign everything = fruits | concat: vegetables | concat: furniture %}
+
+{% for item in everything %}
+- {{ item }}
+{% endfor %}
+```
+
+输出
+```text
+- apples
+- oranges
+- peaches
+- carrots
+- turnips
+- potatoes
+- chairs
+- tables
+- shelves
+```
@@ -0,0 +1,53 @@
+---
+title: date
+---
+
+把时间戳转换为字符串，这一语法的格式同 [`strftime`](http://strftime.net)。LiquidJS 会先通过 [new Date()][newDate] 尝试把输入转换为 Date 对象。
+
+输入
+```liquid
+{{ article.published_at | date: "%a, %b %d, %y" }}
+```
+
+输出
+```text
+Fri, Jul 17, 15
+```
+
+输入
+```liquid
+{{ article.published_at | date: "%Y" }}
+```
+
+输出
+```text
+2015
+```
+
+对于包含格式正确的字符串也好使：
+
+输入
+```liquid
+{{ "March 14, 2016" | date: "%b %d, %y" }}
+```
+
+输出
+```text
+Mar 14, 16
+```
+
+可以用特殊值 `"now"`（或`"today"`）来获取当前时间：
+
+输入
+```liquid
+This page was last updated at {{ "now" | date: "%Y-%m-%d %H:%M" }}.
+```
+
+输出
+```text
+This page was last updated at 2020-03-25 15:57.
+```
+
+{% note info 当前时间 %}注意得到的当前时间是模板渲染时的时间，如果你在用静态站点生成器或者模板有被缓存这一时间可能与用户看到的时间不同。{% endnote %}
+
+[newDate]: https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Date
@@ -0,0 +1,43 @@
+---
+title: default
+---
+
+在值不存在时给一个默认值，如果左侧是 [falsy][falsy] 或空（`string` 或 `Array`）就会使用这个默认值。下面的例子中 `product_price` 没有定义，因此使用了默认值。
+
+输入
+```liquid
+{{ product_price | default: 2.99 }}
+```
+
+输出
+```text
+2.99
+```
+
+下面的例子中定义了 `product_price` 所以没有使用默认值。
+
+输入
+```liquid
+{% assign product_price = 4.99 %}
+{{ product_price | default: 2.99 }}
+```
+
+输出
+```text
+4.99
+```
+
+下面例子中 `product_price` 为空，所以使用了默认值。
+
+输入
+```liquid
+{% assign product_price = "" %}
+{{ product_price | default: 2.99 }}
+```
+
+输出
+```text
+2.99
+```
+
+[falsy]: ../tutorials/truthy-and-falsy.html
@@ -0,0 +1,29 @@
+---
+title: divided_by
+---
+
+两数相除返回商，返回结果数字在 JavaScript 中 `.toString()` 得到的字符串。
+
+输入
+```liquid
+{{ 16 | divided_by: 4 }}
+```
+
+输出
+```text
+4
+```
+
+输入
+```liquid
+{{ 5 | divided_by: 3 }}
+```
+
+输出
+```text
+1.6666666666666667
+```
+
+{% note info Integer Arithmetic %}Since JavaScript doesn't differentiate integers and floats, LiquidJS is not capable of integer arithmetic and the return type is always `number`, the string representation of which depends on its value.{% endnote %}
+
+[floor]: ./floor.html
@@ -0,0 +1,25 @@
+---
+title: downcase
+---
+
+字符串中每个字符都转为小写，对已经是小写的字符没有影响。
+
+输入
+```liquid
+{{ "Parker Moore" | downcase }}
+```
+
+输出
+```text
+parker moore
+```
+
+输入
+```liquid
+{{ "apple" | downcase }}
+```
+
+输出
+```text
+apple
+```
@@ -0,0 +1,25 @@
+---
+title: escape
+---
+
+把字符串中的 HTML 特殊字符转义，对不需要转义的字符串不会产生影响。
+
+输入
+```liquid
+{{ "Have you read 'James & the Giant Peach'?" | escape }}
+```
+
+输出
+<pre class="highlight">
+{{"Have you read &#39;James &amp; the Giant Peach&#39;?" | escape}}
+</pre>
+
+输入
+```liquid
+{{ "Tetsuro Takara" | escape }}
+```
+
+输出
+```text
+Tetsuro Takara
+```
@@ -0,0 +1,25 @@
+---
+title: escape_once
+---
+
+把字符串中的特殊字符转义得到可用在 URL 里的字符串，对已经转义过的字符串和不需要转义的字符串不会产生影响。
+
+输入
+```liquid
+{{ "1 < 2 & 3" | escape_once }}
+```
+
+输出
+<pre class="highlight">
+{{"1 &lt; 2 &amp; 3" | escape}}
+</pre>
+
+输入
+<pre class="highlight">
+&#x7B;&#x7B; "{{"1 &lt; 2 &amp; 3" | escape}}" | escape_once }}
+</pre>
+
+输出
+<pre class="highlight">
+{{"1 &lt; 2 &amp; 3" | escape}}
+</pre>
@@ -0,0 +1,35 @@
+---
+title: first
+---
+
+返回数组的第一个元素。
+
+输入
+```liquid
+{{ "Ground control to Major Tom." | split: " " | first }}
+```
+
+输出
+```text
+Ground
+```
+
+输入
+```liquid
+{% assign my_array = "zebra, octopus, giraffe, tiger" | split: ", " %}
+{{ my_array.first }}
+```
+
+输出
+```text
+
+zebra
+```
+
+需要在标签中使用的时候，可以用点来计算 `first`：
+
+```liquid
+{% if my_array.first == "zebra" %}
+  Here comes a zebra!
+{% endif %}
+```
@@ -0,0 +1,47 @@
+---
+title: floor
+---
+
+数字下取整，LiquidJS 会尝试把输入转换为数字再做下取整操作。
+
+输入
+```liquid
+{{ 1.2 | floor }}
+```
+
+输出
+```text
+1
+```
+
+输入
+```liquid
+{{ 2.0 | floor }}
+```
+
+输出
+```text
+2
+```
+
+输入
+```liquid
+{{ 183.357 | floor }}
+```
+
+输出
+```text
+183
+```
+
+下面的例子中输入是个数字：
+
+输入
+```liquid
+{{ "3.5" | floor }}
+```
+
+输出
+```text
+3
+```
@@ -0,0 +1,17 @@
+---
+title: join
+---
+
+把数组中的元素连接成为一个字符串，以传入的参数作为分隔符。
+
+输入
+```liquid
+{% assign beatles = "John, Paul, George, Ringo" | split: ", " %}
+{{ beatles | join: " and " }}
+```
+
+输出
+```text
+
+John and Paul and George and Ringo
+```
@@ -0,0 +1,16 @@
+---
+title: json
+---
+
+通过 `JSON.stringify()` 把值转换为字符串，多用于调试用途。
+
+输入
+```liquid
+{% assign arr = "foo bar coo" | split: " " %}
+{{ arr | json }}
+```
+
+输出
+```text
+["foo","bar","coo"]
+```
@@ -0,0 +1,35 @@
+---
+title: last
+---
+
+返回数组的最后一个元素。
+
+输入
+```liquid
+{{ "Ground control to Major Tom." | split: " " | last }}
+```
+
+输出
+```text
+Tom.
+```
+
+输入
+```liquid
+{% assign my_array = "zebra, octopus, giraffe, tiger" | split: ", " %}
+{{ my_array.last }}
+```
+
+输出
+```text
+
+tiger
+```
+
+需要在标签中使用的时候，可以用点来计算 `last`：
+
+```liquid
+{% if my_array.last == "tiger" %}
+  There goes a tiger!
+{% endif %}
+```
@@ -0,0 +1,15 @@
+---
+title: lstrip
+---
+
+移除字符串左侧的空白字符（制表符、空格、换行），不影响词之间的空格。
+
+输入
+```liquid
+BEGIN{{ "          So much room for activities!          " | lstrip }}END
+```
+
+输出
+```text
+BEGINSo much room for activities!          END
+```
@@ -0,0 +1,25 @@
+---
+title: map
+---
+
+按照属性名提取对象的属性形成另一个数组并返回。
+
+下面的例子中假设 `site.pages` 包含了站点的所有网页元信息。使用 `assign` 加 `map` 过滤器创建了一个 `site.pages` 中所有对象的 `category` 属性的值构成的数组。
+
+输入
+```liquid
+{% assign all_categories = site.pages | map: "category" %}
+
+{% for item in all_categories %}
+- {{ item }}
+{% endfor %}
+```
+
+输出
+```text
+- business
+- celebrities
+- lifestyle
+- sports
+- technology
+```
@@ -0,0 +1,35 @@
+---
+title: minus
+---
+
+两数相减。
+
+输入
+```liquid
+{{ 4 | minus: 2 }}
+```
+
+输出
+```text
+2
+```
+
+输入
+```liquid
+{{ 16 | minus: 4 }}
+```
+
+输出
+```text
+12
+```
+
+输入
+```liquid
+{{ 183.357 | minus: 12 }}
+```
+
+输出
+```text
+171.357
+```
@@ -0,0 +1,35 @@
+---
+title: modulo
+---
+
+返回两数相除的余数。
+
+输入
+```liquid
+{{ 3 | modulo: 2 }}
+```
+
+输出
+```text
+1
+```
+
+输入
+```liquid
+{{ 24 | modulo: 7 }}
+```
+
+输出
+```text
+3
+```
+
+输入
+```liquid
+{{ 183.357 | modulo: 12 }}
+```
+
+输出
+```text
+3.3569999999999993
+```
@@ -0,0 +1,21 @@
+---
+title: newline_to_br
+---
+
+把字符串里的所有换行符（`\n`）替换为 HTML 换行（`<br />`）。
+
+输入
+```liquid
+{% capture string_with_newlines %}
+Hello
+there
+{% endcapture %}
+
+{{ string_with_newlines | newline_to_br }}
+```
+
+输出
+```html
+
+<br/>Hello<br/>there<br/>
+```
@@ -0,0 +1,17 @@
+---
+title: 过滤器
+---
+
+LiquidJS 支持 Liquid 语法中具体业务无关的过滤器，基本上 [shopify/liquid 核心][shopify/liquid] 支持的 LiquidJS 都支持。这部分包含了所有 LiquidJS 支持的过滤器的文档和使用示例。
+
+LiquidJS 共支持 40+ 个过滤器，可以分为如下几类：
+
+类别 | 过滤器
+--- | ---
+数学 | plus, minus, modulo, times, floor, ceil, round, divided_by, abs
+字符串 | append, prepend, capitalize, upcase, downcase, strip, lstrip, rstrip, strip_newlines, split, replace, replace_first, remove, remove_first, truncate, truncatewords
+HTML/URI | escape, escape_once, url_encode, url_decode, strip_html, newline_to_br
+数组 | slice, map, sort, sort_natural, uniq, wheres, first, last, join, reverse
+日期 | date
+
+[shopify/liquid]: https://github.com/Shopify/liquid
@@ -0,0 +1,35 @@
+---
+title: plus
+---
+
+两数相加。
+
+输入
+```liquid
+{{ 4 | plus: 2 }}
+```
+
+输出
+```text
+6
+```
+
+输入
+```liquid
+{{ 16 | plus: 4 }}
+```
+
+输出
+```text
+20
+```
+
+输入
+```liquid
+{{ 183.357 | plus: 12 }}
+```
+
+输出
+```text
+195.357
+```
@@ -0,0 +1,29 @@
+---
+title: prepend
+---
+
+在字符串开头添加另一个字符串。
+
+输入
+```liquid
+{{ "apples, oranges, and bananas" | prepend: "Some fruit: " }}
+```
+
+输出
+```text
+Some fruit: apples, oranges, and bananas
+```
+
+`prepend` 也可以用于变量。
+
+输入
+```liquid
+{% assign url = "example.com" %}
+{{ "/index.html" | prepend: url }}
+```
+
+输出
+```text
+
+example.com/index.html
+```
@@ -0,0 +1,15 @@
+---
+title: remove
+---
+
+移除字符串中出现的所有指定子字符串。
+
+输入
+```liquid
+{{ "I strained to see the train through the rain" | remove: "rain" }}
+```
+
+输出
+```text
+I strained to see the t through the 
+```
@@ -0,0 +1,15 @@
+---
+title: remove_first
+---
+
+移除字符串中出现的第一个指定子字符串。
+
+输入
+```liquid
+{{ "I strained to see the train through the rain" | remove_first: "rain" }}
+```
+
+输出
+```text
+I strained to see the t through the rain
+```
@@ -0,0 +1,15 @@
+---
+title: replace
+---
+
+把字符串中出现的每一个指定子字符串替换为另一个字符串。
+
+输入
+```liquid
+{{ "Take my protein pills and put my helmet on" | replace: "my", "your" }}
+```
+
+输出
+```text
+Take your protein pills and put your helmet on
+```
@@ -0,0 +1,15 @@
+---
+title: replace_first
+---
+
+把字符串中出现的第一个指定子字符串替换为另一个字符串。
+
+输入
+```liquid
+{{ "Take my protein pills and put my helmet on" | replace_first: "my", "your" }}
+```
+
+输出
+```text
+Take your protein pills and put my helmet on
+```
@@ -0,0 +1,31 @@
+---
+title: reverse
+---
+
+反转数组的所有元素，不可用于字符串。
+
+输入
+```liquid
+{% assign my_array = "apples, oranges, peaches, plums" | split: ", " %}
+
+{{ my_array | reverse | join: ", " }}
+```
+
+输出
+```text
+
+
+plums, peaches, oranges, apples
+```
+
+尽管 `reverse` 不能直接用于字符串，可以把字符串分割成数组，反转后再连接成字符串：
+
+输入
+```liquid
+{{ "Ground control to Major Tom." | split: "" | reverse | join: "" }}
+```
+
+输出
+```text
+.moT rojaM ot lortnoc dnuorG
+```
@@ -0,0 +1,35 @@
+---
+title: round
+---
+
+数字四舍五入取整，如果传入小数位数作为参数。
+
+输入
+```liquid
+{{ 1.2 | round }}
+```
+
+输出
+```text
+1
+```
+
+输入
+```liquid
+{{ 2.7 | round }}
+```
+
+输出
+```text
+3
+```
+
+输入
+```liquid
+{{ 183.357 | round: 2 }}
+```
+
+输出
+```text
+183.36
+```
@@ -0,0 +1,15 @@
+---
+title: rstrip
+---
+
+移除字符串右侧的空白字符（制表符、空格、换行），不影响词之间的空格。
+
+输入
+```liquid
+BEGIN{{ "          So much room for activities!          " | rstrip }}END
+```
+
+输出
+```text
+BEGIN          So much room for activities!END
+```
@@ -0,0 +1,37 @@
+---
+title: size
+---
+
+返回字符串的字符个数或者数组的元素个数。
+
+输入
+```liquid
+{{ "Ground control to Major Tom." | size }}
+```
+
+输出
+```text
+28
+```
+
+输入
+```liquid
+{% assign my_array = "apples, oranges, peaches, plums" | split: ", " %}
+
+{{ my_array.size }}
+```
+
+输出
+```text
+
+
+4
+```
+
+在标签里可以用点来计算 `size`：
+
+```liquid
+{% if site.pages.size > 10 %}
+  This is a big website!
+{% endif %}
+```
@@ -0,0 +1,47 @@
+---
+title: slice
+---
+
+返回第一个参数为下标位置的一个字符，如果指定了第二个参数会被解释为子字符串的长度。字符串下标从零开始。
+
+输入
+```liquid
+{{ "Liquid" | slice: 0 }}
+```
+
+输出
+```text
+L
+```
+
+输入
+```liquid
+{{ "Liquid" | slice: 2 }}
+```
+
+输出
+```text
+q
+```
+
+输入
+```liquid
+{{ "Liquid" | slice: 2, 5 }}
+```
+
+输出
+```text
+quid
+```
+
+If the first argument is a negative number, the indices are counted from the end of the string:
+
+输入
+```liquid
+{{ "Liquid" | slice: -3, 2 }}
+```
+
+输出
+```text
+ui
+```
@@ -0,0 +1,28 @@
+---
+title: sort
+---
+
+对数组中的元素排序，排序方式为 JavaScript `Array.prototype.sort()`。
+
+输入
+```liquid
+{% assign my_array = "zebra, octopus, giraffe, Sally Snake" | split: ", " %}
+
+{{ my_array | sort | join: ", " }}
+```
+
+输出
+```text
+
+
+Sally Snake, giraffe, octopus, zebra
+```
+
+有一个参数来指定用元素的哪个属性排序。
+
+```liquid
+{% assign products_by_price = collection.products | sort: "price" %}
+{% for product in products_by_price %}
+  <h4>{{ product.title }}</h4>
+{% endfor %}
+```
@@ -0,0 +1,28 @@
+---
+title: sort_natural
+---
+
+大小写不敏感地对数组元素排序。
+
+输入
+```liquid
+{% assign my_array = "zebra, octopus, giraffe, Sally Snake" | split: ", " %}
+
+{{ my_array | sort_natural | join: ", " }}
+```
+
+输出
+```text
+
+
+giraffe, octopus, Sally Snake, zebra
+```
+
+有一个参数来指定用元素的哪个属性排序。
+
+```liquid
+{% assign products_by_company = collection.products | sort_natural: "company" %}
+{% for product in products_by_company %}
+  <h4>{{ product.title }}</h4>
+{% endfor %}
+```
@@ -0,0 +1,29 @@
+---
+title: split
+---
+
+把字符串按照指定的分隔符进行分割，`split` 通常用于把逗号分隔的字符串转换为数组。
+
+输入
+```liquid
+{% assign beatles = "John, Paul, George, Ringo" | split: ", " %}
+
+{% for member in beatles %}
+  {{ member }}
+{% endfor %}
+```
+
+输出
+```text
+
+
+
+
+  John
+
+  Paul
+
+  George
+
+  Ringo
+```
@@ -0,0 +1,15 @@
+---
+title: strip
+---
+
+移除字符串两侧的空白字符（制表符、空格、换行），不影响词之间的空格。
+
+输入
+```liquid
+BEGIN{{ "          So much room for activities!          " | strip }}END
+```
+
+输出
+```text
+BEGINSo much room for activities!END
+```
@@ -0,0 +1,15 @@
+---
+title: strip_html
+---
+
+移除字符串中的 HTML 标签。
+
+输入
+```liquid
+{{ "Have <em>you</em> read <strong>Ulysses</strong>?" | strip_html }}
+```
+
+输出
+```text
+Have you read Ulysses?
+```
@@ -0,0 +1,21 @@
+---
+title: strip_newlines
+---
+
+移除字符串中的换行符。
+
+输入
+```liquid
+{% capture string_with_newlines %}
+Hello
+there
+{% endcapture %}
+
+{{ string_with_newlines | strip_newlines }}
+```
+
+输出
+```html
+
+Hellothere
+```
@@ -0,0 +1,35 @@
+---
+title: times
+---
+
+两数相乘。
+
+输入
+```liquid
+{{ 3 | times: 2 }}
+```
+
+输出
+```text
+6
+```
+
+输入
+```liquid
+{{ 24 | times: 7 }}
+```
+
+输出
+```text
+168
+```
+
+输入
+```liquid
+{{ 183.357 | times: 12 }}
+```
+
+输出
+```text
+2200.284
+```
@@ -0,0 +1,45 @@
+---
+title: truncate
+---
+
+把字符串截断为指定长度，可以指定一个数字表示截断到多少长度。最后会添加一个省略号（...）且记在长度里。
+
+## 基本使用
+
+输入
+```liquid
+{{ "Ground control to Major Tom." | truncate: 20 }}
+```
+
+输出
+```text
+Ground control to...
+```
+
+## 自定义省略号
+
+`truncate` 的第二个可选参数用来指定后面追加的字符串，默认为省略号（...）。这个参数的长度会计算在第一个参数的长度里。例如，如果要把字符串截断到 10 个字符，并使用了一个 3 字符长度的省略号，那么第一个参数的值要设置到 **13**。
+
+输入
+```liquid
+{{ "Ground control to Major Tom." | truncate: 25, ", and so on" }}
+```
+
+输出
+```text
+Ground control, and so on
+```
+
+## 不要省略号
+
+如果需要把字符串截断到特定长度且不要添加省略号，则把第二个参数设置为空字符串：
+
+输入
+```liquid
+{{ "Ground control to Major Tom." | truncate: 20, "" }}
+```
+
+输出
+```text
+Ground control to Ma
+```
@@ -0,0 +1,45 @@
+---
+title: truncatewords
+---
+
+把字符串截断为指定个数的单词，可以指定一个数字表示截断到多少个单词。最后会添加一个省略号（...）。
+
+## 基本使用
+
+输入
+```liquid
+{{ "Ground control to Major Tom." | truncatewords: 3 }}
+```
+
+输出
+```text
+Ground control to...
+```
+
+## 自定义省略号
+
+`truncate` 的第二个可选参数用来指定后面追加的字符串，默认为省略号（...）。
+
+输入
+```liquid
+{{ "Ground control to Major Tom." | truncatewords: 3, "--" }}
+```
+
+输出
+```text
+Ground control to--
+```
+
+## 不要省略号
+
+如果不希望添加省略号，把第二个参数设置为空字符串即可：
+
+输入
+```liquid
+{{ "Ground control to Major Tom." | truncatewords: 3, "" }}
+```
+
+输出
+```text
+Ground control to
+```
@@ -0,0 +1,16 @@
+---
+title: uniq
+---
+
+移除数组中的重复元素。
+
+输入
+```liquid
+{% assign my_array = "ants, bugs, bees, bugs, ants" | split: ", " %}
+{{ my_array | uniq | join: ", " }}
+```
+
+输出
+```text
+
+ants, bugs, bees```
@@ -0,0 +1,25 @@
+---
+title: upcase
+---
+
+字符串中每个字符都转为大写，对已经是小写的字符没有影响。
+
+输入
+```liquid
+{{ "Parker Moore" | upcase }}
+```
+
+输出
+```text
+PARKER MOORE
+```
+
+输入
+```liquid
+{{ "APPLE" | upcase }}
+```
+
+输出
+```text
+APPLE
+```
@@ -0,0 +1,15 @@
+---
+title: url_decode
+---
+
+把 URL 编码的字符串解码。
+
+输入
+```liquid
+{{ "%27Stop%21%27+said+Fred" | url_decode }}
+```
+
+输出
+```text
+'Stop!' said Fred
+```
@@ -0,0 +1,25 @@
+---
+title: url_encode
+---
+
+把字符串中 URL 不安全的字符转义为百分号编码。
+
+输入
+```liquid
+{{ "john@liquid.com" | url_encode }}
+```
+
+输出
+```text
+john%40liquid.com
+```
+
+输入
+```liquid
+{{ "Tetsuro Takara" | url_encode }}
+```
+
+输出
+```text
+Tetsuro+Takara
+```
@@ -0,0 +1,80 @@
+---
+title: where
+---
+
+按照数组中对象的属性值来过滤得到新数组，如果未指定第二个参数（属性值）则过滤得到所有属性值为 [truthy][truthy] 的对象。
+
+下面的例子中，假设你有一个 `products` 列表并且希望展示其中的厨房产品。使用 `where` 过滤器可以得到一个只包含 `"type"` 属性值为 `"kitchen"` 的元素的数组。
+
+输入
+```liquid
+All products:
+{% for product in products %}
+- {{ product.title }}
+{% endfor %}
+
+{% assign kitchen_products = products | where: "type", "kitchen" %}
+
+Kitchen products:
+{% for product in kitchen_products %}
+- {{ product.title }}
+{% endfor %}
+```
+
+输出
+```text
+All products:
+- Vacuum
+- Spatula
+- Television
+- Garlic press
+
+Kitchen products:
+- Spatula
+- Garlic press
+```
+
+如果你有一个产品列表且希望只显示可用的产品，可以用 `where` 过滤器但不指定目标值，LiquidJS 会过滤得到 `"available"` 值为 [truthy][truthy] 的产品列表。
+
+输入
+```liquid
+All products:
+{% for product in products %}
+- {{ product.title }}
+{% endfor %}
+
+{% assign available_products = products | where: "available" %}
+
+Available products:
+{% for product in available_products %}
+- {{ product.title }}
+{% endfor %}
+```
+
+输出
+```text
+All products:
+- Coffee mug
+- Limited edition sneakers
+- Boring sneakers
+
+Available products:
+- Coffee mug
+- Boring sneakers
+```
+
+`where` 后面再加一个 `first` 可以用来得到单个元素。例如，你要展示秋季系列里的单个 T-shirt。
+
+输入
+```liquid
+{% assign new_shirt = products | where: "type", "shirt" | first %}
+
+Featured product: {{ new_shirt.title }}
+```
+
+输出
+```text
+Featured product: Hawaiian print sweater vest
+```
+
+[truthy]: ../tutorials/truthy-and-falsy.html
@@ -0,0 +1,29 @@
+layout: index
+description: LiquidJS is a simple, expressive and safe template engine.
+subtitle: 简单安全的 Liquid 模板引擎
+---
+ul#intro-feature-list
+  li.intro-feature-wrap
+    .intro-feature
+      .intro-feature-icon
+        i.icon-shield
+      h3.intro-feature-title 安全渲染
+      p.intro-feature-desc 所有输出都默认经过转义，可以安全地开放给客户使用。运算符和表达式都先解析到 AST 再去渲染，避免了 #[code eval] 和 #[code new Function]。
+  li.intro-feature-wrap
+    .intro-feature
+      .intro-feature-icon
+        i.icon-javascript
+      h3.intro-feature-title 纯 JavaScript
+      p.intro-feature-desc 零 NPM 依赖且没有 Native 绑定的 Liquid 实现，Node.js 和浏览器通用。同时提供了 CDN 可用的 CMD, ESM 和 CJS 打包。
+  li.intro-feature-wrap
+    .intro-feature
+      .intro-feature-icon
+        i.icon-shopify
+      h3.intro-feature-title Shopify 兼容
+      p.intro-feature-desc 支持 #[a(href="https://github.com/shopify/liquid") shopify/liquid] 的所有标签和过滤器，#[a(href="https://jekyllrb.com/") Jekyll 站点], #[a(href="https://pages.github.com/") Github Pages] 和 #[a(href="https://themes.shopify.com/") Shopify 模板] 都可以轻松迁移到 Node.js。
+  li.intro-feature-wrap
+    .intro-feature
+      .intro-feature-icon
+        i.icon-cog
+      h3.intro-feature-title Extensibility
+      p.intro-feature-desc 整个项目在 TypeScript strict 模式下重写，确保了一致的 API 和实时更新的文档。除了 60+ 内置标签和过滤器之外，LiquidJS 还提供了 API 来注册你自己的插件。
@@ -0,0 +1,3 @@
+---
+layout: playground
+---
@@ -0,0 +1,31 @@
+---
+title: Assign
+---
+
+创建一个新变量。
+
+输入
+```liquid
+{% assign my_variable = false %}
+{% if my_variable != true %}
+  This statement is valid.
+{% endif %}
+```
+
+输出
+```text
+This statement is valid.
+```
+
+用引号（`"`）包起来表示一个字符串。
+
+输入
+```liquid
+{% assign foo = "bar" %}
+{{ foo }}
+```
+
+输出
+```text
+bar
+```
@@ -0,0 +1,35 @@
+---
+title: capture
+---
+
+把 `capture` 开闭标签之间的内容渲染后赋值给一个变量，这个变量的类型总是字符串。
+
+输入
+```liquid
+{% capture my_variable %}I am being captured.{% endcapture %}
+{{ my_variable }}
+```
+
+输出
+```text
+I am being captured.
+```
+
+在 `capture` 里可以使用 `assign` 创建的其他变量来构建复杂字符串：
+
+输入
+```liquid
+{% assign favorite_food = "pizza" %}
+{% assign age = 35 %}
+
+{% capture about_me %}
+I am {{ age }} and my favorite food is {{ favorite_food }}.
+{% endcapture %}
+
+{{ about_me }}
+```
+
+输出
+```text
+I am 35 and my favourite food is pizza.
+```
@@ -0,0 +1,23 @@
+---
+title: case
+---
+
+创建一个 switch 语句，把变量跟不同的值比较。`case` 创建 switch 语句，`when` 比较它的值。
+
+输入
+```liquid
+{% assign handle = "cake" %}
+{% case handle %}
+  {% when "cake" %}
+     This is a cake
+  {% when "cookie" %}
+     This is a cookie
+  {% else %}
+     This is not a cake nor a cookie
+{% endcase %}
+```
+
+输出
+```text
+This is a cake
+```
@@ -0,0 +1,17 @@
+---
+title: Comment
+---
+
+让 Liquid 模板里一段代码不渲染。处于 `comment` 开闭标签之间的文本都不会输出，Liquid 代码都不会执行。
+
+输入
+```liquid
+Anything you put between {% comment %} and {% endcomment %} tags
+is turned into a comment.
+```
+
+输出
+```liquid
+Anything you put between  tags
+is turned into a comment.
+```
@@ -0,0 +1,48 @@
+---
+title: cycle
+---
+
+循环一组字符串按照它们传入的顺序打印出来。每次调用 `cycle` 打印下一个参数。
+
+## 基本使用
+
+输入
+```liquid
+{% cycle "one", "two", "three" %}
+{% cycle "one", "two", "three" %}
+{% cycle "one", "two", "three" %}
+{% cycle "one", "two", "three" %}
+```
+
+输出
+```text
+one
+two
+three
+one
+```
+
+`cycle` 可以用于：
+
+- 对表格里每一行按奇偶应用不同样式
+- 对每行最后一项应用特殊样式
+
+## 参数
+
+一个模板中需要多个 `cycle` 时可以使用 "cycle 组" 参数。如果没有提供组名，使用同样参数调用的 `cycle` 会被认为处于同一组。
+
+输入
+```liquid
+{% cycle "first": "one", "two", "three" %}
+{% cycle "second": "one", "two", "three" %}
+{% cycle "second": "one", "two", "three" %}
+{% cycle "first": "one", "two", "three" %}
+```
+
+输出
+```text
+one
+one
+two
+two
+```
@@ -0,0 +1,25 @@
+---
+title: Decrement
+---
+
+创建一个新的数字类型的变量，每次调用都把它的值减一。第一次是 `-1`。
+
+输入
+```liquid
+{% decrement variable %}
+{% decrement variable %}
+{% decrement variable %}
+```
+
+输出
+```text
+-1
+-2
+-3
+```
+
+像 [increment][increment] 一样，在 `decrement` 里声明的变量独立于 [assign][assign] 或 [capture][capture] 创建的变量。
+
+[increment]: ./increment.html
+[assign]: ./assign.html
+[capture]: ./capture.html
@@ -0,0 +1,201 @@
+---
+title: For
+---
+
+重复执行代码块的迭代标签。
+
+## 基本使用
+
+### for...in
+
+重复执行一段代码。
+
+输入
+```liquid
+{% for product in collection.products %}
+  {{ product.title }}
+{% endfor %}
+```
+
+输出
+```text
+hat shirt pants
+```
+
+### else
+
+指定 `for` 循环的集合长度为零时执行的代码块。
+
+输入
+```liquid
+{% for product in collection.products %}
+  {{ product.title }}
+{% else %}
+  The collection is empty.
+{% endfor %}
+```
+
+输出
+```text
+The collection is empty.
+```
+
+### break
+
+遇到 `break` 标签时 `for` 循环停止执行。
+
+输入
+```liquid
+{% for i in (1..5) %}
+  {% if i == 4 %}
+    {% break %}
+  {% else %}
+    {{ i }}
+  {% endif %}
+{% endfor %}
+```
+
+输出
+```text
+1 2 3
+```
+
+### continue
+
+遇到 `continue` 标签时跳过当前这次迭代。
+
+输入
+```liquid
+{% for i in (1..5) %}
+  {% if i == 4 %}
+    {% continue %}
+  {% else %}
+    {{ i }}
+  {% endif %}
+{% endfor %}
+```
+
+输出
+```text
+1 2 3   5
+```
+
+### forloop
+
+在 `for` 循环里有一个 `forloop` 变量可用，用来表示迭代的当前状态。
+
+`forloop.first`, `forloop.last` 和 `forloop.length` 属性：
+
+输入
+```
+{% for i in (1..5) %}
+  {%- if forloop.first == true -%} First
+  {%- elsif forloop.last == true -%} Last
+  {%- else -%} {{ forloop.length }}
+  {%- endif %}
+{% endfor -%}
+```
+
+输出
+```
+First
+5
+5
+5
+Last
+```
+
+`forloop.index`, `forloop.index0`, `forloop.rindex` 和 `forloop.rindex0` 属性：
+
+输入
+```
+index index0 rindex rindex0
+{% for i in (1..5) %}
+  {{- forloop.index }}     {{ forloop.index0 }}      {{ forloop.rindex }}      {{ forloop.rindex0 }}
+{% endfor -%}
+```
+
+输出
+```
+index index0 rindex rindex0
+1     0      5      4
+2     1      4      3
+3     2      3      2
+4     3      2      1
+5     4      1      0
+```
+
+## 参数
+
+### limit
+
+限制循环执行的次数。
+
+输入
+```liquid
+<!-- if array = [1,2,3,4,5,6] -->
+{% for item in array limit:2 %}
+  {{ item }}
+{% endfor %}
+```
+
+输出
+```text
+1 2
+```
+
+### offset
+
+从指定的下标处开始循环。
+
+输入
+```liquid
+<!-- if array = [1,2,3,4,5,6] -->
+{% for item in array offset:2 %}
+  {{ item }}
+{% endfor %}
+```
+
+输出
+```text
+3 4 5 6
+```
+
+### range
+
+定义一个用于循环的数字范围。可以用字面量定义范围，也可以用变量定义范围。
+
+输入
+```liquid
+{% for i in (3..5) %}
+  {{ i }}
+{% endfor %}
+
+{% assign num = 4 %}
+{% for i in (1..num) %}
+  {{ i }}
+{% endfor %}
+```
+
+输出
+```text
+3 4 5
+1 2 3 4
+```
+
+### reversed
+
+反转循环的顺序。注意这个参数的拼写和过滤器 `reverse` 不同。
+
+输入
+```liquid
+<!-- if array = [1,2,3,4,5,6] -->
+{% for item in array reversed %}
+  {{ item }}
+{% endfor %}
+```
+
+输出
+```text
+6 5 4 3 2 1
+```
@@ -0,0 +1,42 @@
+---
+title: If
+---
+
+条件为 `true` 时执行某个代码块。
+
+## if
+
+输入
+```liquid
+{% if product.title == "Awesome Shoes" %}
+  These shoes are awesome!
+{% endif %}
+```
+
+输出
+```text
+These shoes are awesome!
+```
+
+## elsif / else
+
+在 `if` 或 [unless][unless] 块中添加更多的条件。
+
+输入
+```liquid
+<!-- If customer.name = "anonymous" -->
+{% if customer.name == "kevin" %}
+  Hey Kevin!
+{% elsif customer.name == "anonymous" %}
+  Hey Anonymous!
+{% else %}
+  Hi Stranger!
+{% endif %}
+```
+
+输出
+```text
+Hey Anonymous!
+```
+
+[unless]: ./unless.html
@@ -0,0 +1,46 @@
+---
+title: Include
+---
+
+{% note warn 已废弃 %}
+这个标签已经废弃，请使用封装更好的 <a href="./render.html">render</a> 标签。
+{% endnote %}
+
+## 引入一个模板
+
+从模板 [根路径][root] 引入一个模板：
+
+```liquid
+{% include 'footer.liquid' %}
+```
+
+设置 [extname][extname] 选项为 `".liquid"` 后上面的 `.liquid` 后缀就可以省略了，等价于：
+
+```liquid
+{% include 'footer' %}
+```
+
+通过 `include` 渲染一个子模板时，它内部的代码可以访问父模板的变量，但父模板中不能访问它里面定义的变量。
+
+## 变量传递
+
+父模板里定义的变量可以通过 `include` 标签的参数列表传递给子模板：
+
+```liquid
+{% assign my_variable = 'apples' %}
+{% include 'name', my_variable: my_variable, my_other_variable: 'oranges' %}
+```
+
+## `with` 参数
+
+使用 `with...as` 语法可以给子模板传递一个变量：
+
+```liquid
+{% assign featured_product = all_products['product_handle'] %}
+{% include 'product' with featured_product as product %}
+```
+
+上面的例子中，子模板中 `product` 会保有父模板中的 `featured_product` 变量的值。
+
+[extname]: ../../api/interfaces/liquid_options_.liquidoptions.html#Optional-extname
+[root]: ../../api/interfaces/liquid_options_.liquidoptions.html#Optional-root
@@ -0,0 +1,43 @@
+---
+title: Increment
+---
+
+创建一个新的数字类型的变量，每次调用都把它的值加一。第一次为 `0`。
+
+输入
+```liquid
+{% increment my_counter %}
+{% increment my_counter %}
+{% increment my_counter %}
+```
+
+输出
+```text
+0
+1
+2
+```
+
+在 `increment` 里声明的变量独立于 [assign][assign] 或 [capture][capture] 创建的变量。
+
+下面的例子中通过 `assign` 创建了变量 `var`。然后用 `increment` 标签在同名变量上多次递增。注意 `increment` 标签不会影响 `assign` 创建的 `var` 的值。
+
+输入
+```liquid
+{% assign var = 10 %}
+{% increment var %}
+{% increment var %}
+{% increment var %}
+{{ var }}
+```
+
+输出
+```text
+0
+1
+2
+10
+```
+
+[assign]: ./assign.html
+[capture]: ./capture.html
@@ -0,0 +1,64 @@
+---
+title: Layout
+---
+
+## 使用布局模板
+
+套用模板 [根路径][root] 下的某个布局模板中。
+
+```liquid
+{% layout 'footer.liquid' %}
+```
+
+设置 [extname][extname] 选项为 `".liquid"` 后上面的 `.liquid` 后缀就可以省略了，等价于：
+
+```liquid
+{% layout 'footer' %}
+```
+
+通过 `layout` 渲染一个子模板时，它内部的代码可以访问父模板的变量，但父模板中不能访问它里面定义的变量。
+
+## 变量传递
+
+当前模板里定义的变量可以通过 `layout` 标签的参数列表传递给布局模板：
+
+```liquid
+{% assign my_variable = 'apples' %}
+{% layout 'name', my_variable: my_variable, my_other_variable: 'oranges' %}
+```
+
+## 块
+
+布局模板中可以包含若干 `block` 标签，这些 `block` 渲染时会按照子模板提供的内容进行填充。例如我们有布局模板 `default-layout.liquid`：
+
+```
+Header
+{% block content %}My default content{% endblock %}
+Footer
+```
+
+它被子模板 `page.liquid` 通过 `layout` 标签引用：
+
+```
+{% layout "default-layout" %}
+{% block content %}My page content{% endblock %}
+```
+
+`page.liquid` 的渲染结果将会是：
+
+```
+Header
+My page content
+Footer
+```
+
+{% note tip 块 %}
+<ul>
+    <li>一个布局模板中可以定义多个块；</li>
+    <li>如果只有一个块，它的名字可以省略。</li>
+    <li>如果子模板未定义块的内容，将会使用父模板中提供的默认内容。</li>
+</ul>
+{% endnote %}
+
+[extname]: ../../api/interfaces/liquid_options_.liquidoptions.html#Optional-extname
+[root]: ../../api/interfaces/liquid_options_.liquidoptions.html#Optional-root
@@ -0,0 +1,17 @@
+---
+title: 标签
+---
+
+LiquidJS 支持 Liquid 语法中具体业务无关的标签，包含 [shopify/liquid 核心][shopify/liquid] 里的所有标签。这部分包含了所有 LiquidJS 支持的标签的文档和使用示例。
+
+LiquidJS 支持十几个过滤器，可以分为如下几类：
+
+类别 | 用途 | 标签
+--- | --- | ---
+迭代 | 遍历一个集合 | for, cycle, tablerow
+控制流 | 控制模板渲染的执行分支 | if, unless, elif, else, case, when
+变量 | 定义和修改变量 | assign, increment, decrement
+文件 | 引入或继承其他模板 | render, include, layout
+语言 | 暂时禁用 Liquid 语法 | raw, comment
+
+[shopify/liquid]: https://github.com/Shopify/liquid
@@ -0,0 +1,18 @@
+---
+title: Raw
+---
+
+`raw` 标签可以暂时禁用 LiquidJS 的语法。生成和 Liquid 冲突的语言（比如 Nunjucks、Handlebars）时很有用。
+
+输入
+```liquid
+{% raw %}
+  In Handlebars, {{ this }} will be HTML-escaped, but
+  {{{ that }}} will not.
+{% endraw %}
+```
+
+输出
+```text
+In Handlebars, {{ this }} will be HTML-escaped, but {{{ that }}} will not.
+```
@@ -0,0 +1,63 @@
+---
+title: Render
+---
+
+## 基本使用
+
+### 渲染一个模板
+
+从模板 [根路径][root] 引入一个模板：
+
+```liquid
+{% render 'footer.liquid' %}
+```
+
+设置 [extname][extname] 选项为 `".liquid"` 后上面的 `.liquid` 后缀就可以省略了，等价于：
+
+```liquid
+{% render 'footer' %}
+```
+
+{% note info 变量作用域 %}
+通过 `render` 渲染一个子模板时，它内部的代码不能访问父模板的变量，父模板中也不能访问它里面定义的变量。这个封装会让模板代码更容易理解和维护。{% endnote %}
+
+### 变量传递
+
+父模板里定义的变量可以通过 `render` 标签的参数列表传递给子模板：
+
+```liquid
+{% assign my_variable = 'apples' %}
+{% render 'name', my_variable: my_variable, my_other_variable: 'oranges' %}
+```
+
+[全局变量][globals] 不需要传递，所有文件都可以访问它们。
+
+## 参数
+
+### `with` 参数
+
+使用 `with...as` 语法可以给子模板传递一个变量：
+
+```liquid
+{% assign featured_product = all_products['product_handle'] %}
+{% render 'product' with featured_product as product %}
+```
+
+上面的例子中，子模板中 `product` 会保有父模板中的 `featured_product` 变量的值。
+
+### `for` 参数
+
+用 `for...as` 语法可以对可枚举对象的每一个值渲染一次子模板：
+
+```liquid
+{% assign variants = product.variants %}
+{% render 'variant' for variants as variant %}
+```
+
+上面的例子中，对 `product` 的每个 `variants` 是指都会渲染一次子模板。子模板中 `variant` 变量会保有父模板中的 `product.variants` 中对应元素的值。
+
+{% note tip forloop 对象 %} 使用 for 参数时，在子模板中可以访问 <a href="./for.html#forloop">forloop</a> 对象。{% endnote %}
+
+[extname]: ../../api/interfaces/liquid_options_.liquidoptions.html#Optional-extname
+[root]: ../../api/interfaces/liquid_options_.liquidoptions.html#Optional-root
+[globals]: ../../api/interfaces/liquid_options_.liquidoptions.html#Optional-globals
@@ -0,0 +1,128 @@
+---
+title: Table Row
+---
+
+生成一个 HTML 表示，上下必须用 `<table>` 和 `</table>` HTML 标签包裹起来。
+
+## 基本使用
+
+输入
+```liquid
+<table>
+{% tablerow product in collection.products %}
+  {{ product.title }}
+{% endtablerow %}
+</table>
+```
+
+输出
+```html
+<table>
+  <tr class="row1">
+    <td class="col1">
+      Cool Shirt
+    </td>
+    <td class="col2">
+      Alien Poster
+    </td>
+    <td class="col3">
+      Batman Poster
+    </td>
+    <td class="col4">
+      Bullseye Shirt
+    </td>
+    <td class="col5">
+      Another Classic Vinyl
+    </td>
+    <td class="col6">
+      Awesome Jeans
+    </td>
+  </tr>
+</table>
+```
+
+## 参数
+
+### cols
+
+定义表格的列数。
+
+输入
+```liquid
+{% tablerow product in collection.products cols:2 %}
+  {{ product.title }}
+{% endtablerow %}
+```
+
+输出
+```html
+<table>
+  <tr class="row1">
+    <td class="col1">
+      Cool Shirt
+    </td>
+    <td class="col2">
+      Alien Poster
+    </td>
+  </tr>
+  <tr class="row2">
+    <td class="col1">
+      Batman Poster
+    </td>
+    <td class="col2">
+      Bullseye Shirt
+    </td>
+  </tr>
+  <tr class="row3">
+    <td class="col1">
+      Another Classic Vinyl
+    </td>
+    <td class="col2">
+      Awesome Jeans
+    </td>
+  </tr>
+</table>
+```
+
+### limit
+
+限制迭代次数。
+
+```liquid
+{% tablerow product in collection.products cols:2 limit:3 %}
+  {{ product.title }}
+{% endtablerow %}
+```
+
+### offset
+
+从指定的下标处开始循环。
+
+```liquid
+{% tablerow product in collection.products cols:2 offset:3 %}
+  {{ product.title }}
+{% endtablerow %}
+```
+
+### range
+
+定义一个用于循环的数字范围。可以用字面量定义范围，也可以用变量定义范围。
+
+```liquid
+<!--variable number example-->
+
+{% assign num = 4 %}
+<table>
+{% tablerow i in (1..num) %}
+  {{ i }}
+{% endtablerow %}
+</table>
+
+<!--literal number example-->
+
+<table>
+{% tablerow i in (3..5) %}
+  {{ i }}
+{% endtablerow %}
+</table>
+```
@@ -0,0 +1,25 @@
+---
+title: Unless
+---
+
+和 `if` 相反 —— 条件 **不满足** 时执行代码块。
+
+输入
+```liquid
+{% unless product.title == "Awesome Shoes" %}
+  These shoes are not awesome.
+{% endunless %}
+```
+
+输出
+```text
+These shoes are not awesome.
+```
+
+等价于执行下面的代码：
+
+```liquid
+{% if product.title != "Awesome Shoes" %}
+  These shoes are not awesome.
+{% endif %}
+```
@@ -0,0 +1,54 @@
+---
+title: 缓存
+---
+
+在典型的网站项目中，同一个模板文件可能会反复地用不同数据去渲染。在生产环境下模板文件的内容不太会发生变化（除非重新部署了服务），因此可以把从磁盘读取的文件内容和解析得到的模板结构（AST）缓存下来重复使用来节省渲染时间。
+
+LiquidJS 在这一方面比较灵活，提供了多种不同的方式来达到提升性能的目的。
+
+## 手动缓存
+
+[.parse()][parse], [.parseFile()][parseFile], [.parseFileSync()][parseFileSync] API 可以用来把字符串或文件解析成模板。得到的模板可以用不同的数据去重复地渲染得到不同的 HTML。
+
+从字符串解析：
+
+```javascript
+var tpl = engine.parse('{{name | capitalize}}');
+
+engine.renderSync(tpl, {name: 'alice'}) // 'Alice'
+engine.renderSync(tpl, {name: 'bob'}) // 'Bob'
+```
+
+从文件解析：
+
+```javascript
+var tpl = engine.parseFileSync('hello');    // contents of `hello.liquid`: {{name}}
+
+engine.renderSync(tpl, {name: 'alice'}) // 'Alice'
+engine.renderSync(tpl, {name: 'bob'}) // 'Bob'
+```
+
+上述代码中字符串或文件只被解析了一次，可以反复利用去渲染不同的数据。有很多模板文件时可以把 `tpl` 变量存在 `Map` 中，后续再 `.render()` 时直接从 Map 中拿出解析好的模板去渲染。
+
+## `cache` 选项
+
+如果你只用 `.renderFile()` 和 `.renderFileSync()` 也可以直接设置 [cache][cache] 选项，LiquidJS 会帮你缓存。
+
+```javascript
+var { Liquid } = require('liquidjs');
+var engine = new Liquid({
+    cache: true
+});
+
+// LiquidJS 将会解析 hello.liquid 然后用 {name: 'alice'} 渲染它
+engine.renderFileSync('hello', {name: 'alice'})
+
+// LiquidJS 会找到上次 hello.liquid 解析的结果模板，再用 {name: 'bob'} 渲染它
+engine.renderFileSync('hello', {name: 'bob'})
+```
+
+[parse]: ../../api/classes/liquid_.liquid.html#parse
+[parseFile]: ../../api/classes/liquid_.liquid.html#parseFile
+[parseFileSync]: ../../api/classes/liquid_.liquid.html#parseFileSync
+[renderFile]: ../../api/classes/liquid_.liquid.html#renderFile
+[renderFileSync]: ../../api/classes/liquid_.liquid.html#renderFilesync
@@ -0,0 +1,39 @@
+---
+title: 贡献指南
+---
+
+## 发起 Pull Request
+
+**代码风格**：LiquidJS 采用 [standard](https://github.com/standard/eslint-config-standard) 和 [@typescript-eslint/recommended](https://github.com/typescript-eslint/typescript-eslint/blob/master/packages/eslint-plugin/src/configs/recommended.json) 规则，提交前确保可以通过风格检查：
+
+```bash
+npm run lint
+```
+
+**测试**：确保你改动之后测试仍然可以通过：
+
+```bash
+npm test
+```
+
+**提交消息**：请遵守 [Angular 提交消息规范](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits)，尤其注意 [type 标识](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#type)，semantic-release 机器人依赖这个标识自动发布。
+
+## Star on Github 👉 [![harttle/liquidjs](https://img.shields.io/github/stars/harttle/liquidjs?style=flat-square)][liquidjs]
+
+这是支持我们最简单的方式：通过提升排名来让更多人了解，让它得到更好的改进。
+
+## 成为赞助者！
+
+LiquidJS 是开源的、免费的，并且 **没有** 商业支持，也 **没有** 任何广告。如果你喜欢 LiquidJS 或你的公司在使用 LiquidJS，请考虑通过 [Open Collective][oc] 或 [Patreon][pt] 赞助，作为感谢你的名字和头像（或 Logo）会展示在这里和 [Github README][liquidjs]。
+
+<object type="image/svg+xml" data="https://opencollective.com/liquidjs/tiers/backer.svg?avatarHeight=72"></object>
+
+[![Become a Patron!](../../icon/[email protected])](https://www.patreon.com/bePatron?u=32321060)
+
+[oc]: https://opencollective.com/liquidjs/
+[pt]: https://www.patreon.com/harttle
+[shopify/liquid]: https://shopify.github.io/liquid/
+[caniuse-promises]: http://caniuse.com/#feat=promises
+[pp]: https://github.com/taylorhakes/promise-polyfill
+[tutorial]: https://shopify.github.io/liquid/basics/introduction/
+[liquidjs]: https://github.com/harttle/liquidjs
@@ -0,0 +1,29 @@
+---
+title: 迁移到 LiquidJS 9
+---
+
+LiquidJS 9 有一些基础性的改进，包括一些缺陷修复、新特性、性能提升，也有一些不兼容的变更。
+
+## 新特性
+
+* 同步渲染：新增了 renderSync, parseAndRenderSync, renderFileSync API
+* 新的工具：Expression 和 Tokenizer
+
+## 修复
+
+* 布尔逻辑运算顺序，见 [#130](https://github.com/harttle/liquidjs/issues/130)；
+* `break` 和 `continue` 会忽略它们之前的代码，见 [#123](https://github.com/harttle/liquidjs/issues/123)；
+* React.js 示例无法正确 yarn install，见 [#145](https://github.com/harttle/liquidjs/issues/145)；
+* 有时没有正确地等待 Promise 类型的 Drops。
+
+## 性能
+
+* 目标平台提升到 Node.js 8 引起的性能提升（去掉了一些 Polyfill），见 [#137](https://github.com/harttle/liquidjs/issues/137)；
+* 内存使用降低了 57.5%，见 [#202](https://github.com/harttle/liquidjs/pull/202)；
+* 渲染性能提升了 100.3%，见 [#205](https://github.com/harttle/liquidjs/pull/205)。
+
+## 不兼容的变更
+
+* LiquidJS 不再有默认导出了，以后要使用 `import {Liquid} from 'liquidjs'` 语法。使用 UMD 包里的 `window.Liquid` 也需要改为 `window.liquidjs.Liquid`；
+* 移除了重复的静态方法 `Liquid.evalValue`，统一使用示例方法 `liquid.evalValue`；
+* 支持的最低目标平台为 Node.js 8，CJS 包（Node.js 下的主入口）不再支持 Node.js &leq; 6 了，ESM（dist/liquid.esm.js）和 UMD（dist/liquid.js, dist/liquid.min.js）包不受影响。
@@ -0,0 +1,21 @@
+---
+title: 运算符
+---
+
+LiquidJS 运算符非常简单也很特别，只支持两类运算符：
+
+* 比较运算符：`==`, `!=`, `>`, `<`, `>=`, `<=`
+* 逻辑运算符：`or`, `and`, `contains`
+
+因此普通的数学运算是不支持的，比如 `{% raw %}{{a + b}}{% endraw %}`。它的替代方案是过滤器 `{% raw %}{{ a | plus: b}}{% endraw %}`。事实上 `+` 在 LiquidJS 中是一个合法的变量名。
+
+## 优先级
+
+1. 比较运算符。所有比较运算符具有同样的优先级，且高于逻辑运算符。
+2. 逻辑运算符。所有逻辑运算符具有同样的有衔接。
+
+## 结合性
+
+逻辑运算符是又结合的，所以连续的逻辑运算时计算顺序是从右向左，参考 [Shopify][operator-order] 的文档。
+
+[operator-order]: https://help.shopify.com/en/themes/liquid/basics/operators#order-of-operations
@@ -0,0 +1,75 @@
+---
+title: 概述
+---
+
+LiquidJS 是一个简单的、安全的、兼容 Shopify 的、纯 JavaScript 编写的模板引擎。这个项目的目的是为 JavaScript 社区提供一个 Liquid 模板引擎的实现。
+
+## 在 Node.js 里使用
+
+通过 NPM 安装：
+
+```bash
+npm install --save liquidjs
+```
+
+```javascript
+var { Liquid } = require('liquidjs');
+var engine = new Liquid();
+
+engine
+    .parseAndRender('{{name | capitalize}}', {name: 'alice'})
+    .then(console.log);     // 输出 'Alice'
+```
+
+{% note info 示例 %} 这里有一个 LiquidJS 在 Node.js 里使用的例子：<a href="https://github.com/harttle/liquidjs/blob/master/demo/nodejs/" target="_blank">liquidjs/demo/nodejs/</a>.{% endnote %}
+
+LiquidJS 的类型定义也导出并发布到了 NPM 包里，写 TypeScript 的项目可以直接这样使用：
+
+```typescript
+import { Liquid } from 'liquidjs';
+const engine = new Liquid();
+
+engine
+    .parseAndRender('{{name | capitalize}}', {name: 'alice'})
+    .then(console.log);     // 输出 'Alice'
+```
+
+{% note info 示例 %} 这里有一个 LiquidJS 在 TypeScript 下的例子：<a href="https://github.com/harttle/liquidjs/blob/master/demo/typescript/" target="_blank">liquidjs/demo/typescript/</a>.{% endnote %}
+
+## 在浏览器里使用
+
+LiquidJS 预先构建了 UMD 打包（包括压缩版和未压缩版），可以通过 NPM 包来使用：
+
+```html
+<script src="//unpkg.com/liquidjs/dist/liquid.min.js"></script>     <!--生产环境-->
+<script src="//unpkg.com/liquidjs/dist/liquid.js"></script>         <!--开发环境t-->
+```
+
+或者直接引用 jsDelivr CDN 上的版本：
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/liquidjs/dist/liquid.min.js"></script>     <!--生产环境-->
+<script src="https://cdn.jsdelivr.net/npm/liquidjs/dist/liquid.js"></script>         <!--开发环境t-->
+```
+
+{% note info 示例 %} 这里有一个 jsFiddle 上的在线例子：<a href="https://jsfiddle.net/x43eb0z6/" target="_blank">jsfiddle.net/x43eb0z6</a>，其源码也可以在 <a href="https://github.com/harttle/liquidjs/blob/master/demo/browser/" target="_blank">liquidjs/demo/browser/</a> 找到。{% endnote %}
+
+{% note warn 兼容性 %} 在类似 IE 和 Android UC 这样的浏览器中，你可能需要引入 <a href="https://github.com/taylorhakes/promise-polyfill" target="_blank">Promise polyfill</a>，参看 <a href="http://caniuse.com/#feat=promises" target="_blank">caniuse 的统计</a>。 {% endnote %}
+
+## 在命令行里使用
+
+你还可以在命令行里使用 LiquidJS：
+
+```bash
+echo '{{"hello" | capitalize}}' | npx liquidjs
+```
+
+模板来自标准输入，数据则来自参数，这个参数可以是一个 JSON 文件的路径，也可以是一个 JSON 字符串：
+
+```bash
+echo 'Hello, {{ name }}.' | npx liquidjs '{"name": "Snake"}'
+```
+
+## 其他
+
+[@stevenanthonyrevo](https://github.com/stevenanthonyrevo) 还提供了一个 ReactJS demo，请参考 [liquidjs/demo/reactjs/](https://github.com/harttle/liquidjs/blob/master/demo/reactjs/)。
@@ -0,0 +1,56 @@
+---
+title: 引用和继承
+---
+
+## 引用模板片段
+
+对于如下两个模板文件：
+
+```
+// 文件：color.liquid
+color: '{{ color }}' shape: '{{ shape }}'
+
+// 文件：theme.liquid
+{% assign shape = 'circle' %}
+{% include 'color' %}
+{% include 'color' with 'red' %}
+{% include 'color', color: 'yellow', shape: 'square' %}
+```
+
+输出为：
+
+```
+color: '' shape: 'circle'
+color: 'red' shape: 'circle'
+color: 'yellow' shape: 'square'
+```
+
+## 布局模板（模板继承）
+
+对于如下两个模板文件：
+
+```
+// 文件：default-layout.liquid
+Header
+{% block content %}My default content{% endblock %}
+Footer
+
+// 文件：page.liquid
+{% layout "default-layout" %}
+{% block content %}My page content{% endblock %}
+```
+
+渲染 `page.liquid` 将会输出：
+
+```
+Header
+My page content
+Footer
+```
+
+{% note tip Block %}
+<ul>
+    <li>布局文件（父模板）中可以定义多个 block；</li>
+    <li>只有一个 block 时，block 名字可以省略。</li>
+</ul>
+{% endnote %}
@@ -0,0 +1,49 @@
+---
+title: 插件
+---
+
+一组标签和过滤器可以封装为一个 **插件**，通常发包到 NPM 来方便使用。本文介绍如何创建和使用插件。
+
+## 编写插件
+
+LiquidJS 插件就是一个简单的函数，它的第一个参数是 [Liquid 类][liquid]，其中的 `this` 是它被注册到的 Liquid 实例。可以通过 `this` 来调用 Liquid API，比如 [注册标签和过滤器][register]。
+
+现在我们来写一个插件并在其中注册一个过滤器，来把输入字符串转换为大写：
+
+```javascript
+/**
+ * Inside the plugin function, `this` refers to the Liquid instance.
+ *
+ * @param Liquid: provides facilities to implement tags and filters.
+ */
+module.exports = function (Liquid) {
+    this.registerFilter('upup', x => x.toUpperCase());
+}
+```
+
+把上述代码保存为 `upup.js`。
+
+## 使用插件
+
+把插件传递给 `.plugin()` 方法即可注册插件，例如：
+
+```javascript
+const engine = new Liquid()
+
+engine.plugin(require('./upup.js'));
+engine.parseAndRender('{{ "foo" | upup }}').then(console.log)
+```
+
+上述代码将会输出 `"FOO"`。
+
+## 插件列表
+
+由于本仓库只包含 [Shopify/liquid](https://github.com/Shopify/liquid/) 核心仓库的标签和插件（参考 <https://github.com/harttle/liquidjs#differences-and-limitations>），Shopify 平台上特有的插件只能通过插件来使用。
+
+这里是一个插件列表，欢迎添加你的插件（点击右上角编辑按钮）：
+
+* Sections 标签（开发中）： https://github.com/harttle/liquidjs-section-tags
+* 颜色过滤器： https://github.com/harttle/liquidjs-color-filters
+
+[liquid]: ../../api/classes/liquid_.liquid.html
+[register]: ./register-filters-tags.html
@@ -0,0 +1,39 @@
+---
+title: 注册标签和过滤器
+---
+
+## 注册标签
+
+```javascript
+// 使用方式: {% upper name%}
+engine.registerTag('upper', {
+    parse: function(tagToken, remainTokens) {
+        this.str = tagToken.args; // name
+    },
+    render: async function(scope, hash) {
+        var str = await this.liquid.evalValue(this.str, scope); // 'alice'
+        return str.toUpperCase()  // 'Alice'
+    }
+});
+```
+
+* `parse`: 从 `remainTokens` 中读取后续的标签/输出/HTML，直到找到你期望的结束标签。
+* `render`: 把 scope 数据和此前解析得到的 Token 结合，输出 HTML 字符串。
+
+查看已有的标签实现：<https://github.com/harttle/liquidjs/tree/master/src/builtin/tags>
+
+## 注册过滤器
+
+```javascript
+// 使用方式: {{ name | upper }}
+engine.registerFilter('upper', v => v.toUpperCase())
+```
+
+过滤器的参数将会传递给上面注册的过滤器函数，从第二个参数开始（第一个参数是过滤器左侧的输入），例如：
+
+```javascript
+// Usage: {{ 1 | add: 2, 3 }}
+engine.registerFilter('add', (initial, arg1, arg2) => initial + arg1 + arg2)
+```
+
+查看已有的过滤器实现：<https://github.com/harttle/liquidjs/tree/master/src/builtin/filters>
@@ -0,0 +1,113 @@
+---
+title: 渲染文件
+---
+
+一个典型的项目会有一个目录下都是模板，最方便的方式就是设置 LiquidJS 的 [root][root] 然后调用 [.renderFile()][renderFile] 或 [.renderFileSync()][renderFileSync] 来渲染其中的一个模板文件。
+
+## 渲染一个文件
+
+例如你有如下的目录结构：
+
+```
+.
+├── index.js
+└── views/
+  ├── hello.liquid
+  └── world.liquid
+```
+
+其中 `hello.liquid` 内容为：
+
+```liquid
+name: {{name}}
+```
+
+在 `index.js` 中可以这样渲染 `hello.liquid`:
+
+```javascript
+var engine = new Liquid({
+    root: path.resolve(__dirname, 'views/'), // 设置模板查找目录
+    extname: '.liquid' // 添加后缀，默认为 "" 表示不添加后缀
+});
+// 将会读取并渲染 `views/hello.liquid`
+engine.renderFile("hello", {name: 'alice'}).then(console.log)
+```
+
+执行 `node index.js` 你将会得到类似这样的输出：
+
+```
+name: alice
+```
+
+## 模板查找
+
+传递给 [.renderFile()][renderFile], [.parseFile()][parseFile] [.renderFileSync()][renderFileSync], [.parseFileSync()][parseFileSync] 这些 API 的模板名，
+以及传递给 [include][include], [layout][layout] 这些标签的模板名，将会根据 [root][root] 选项来查找。
+
+`root` 可以设置为 `string` 类型的路径（见上面的例子）， 也可以设置为一个字符串数组表示路径列表，这时 LiquidJS 将会按顺序去查找。例如：
+
+```javascript
+var engine = new Liquid({
+    root: ['views/', 'views/partials/'],
+    extname: '.liquid'
+});
+```
+
+{% note tip 相对路径 %}<code>root</code> 中使用相对路径将会被解释为相对于 <code>cwd()</code>（当前工作目录）。{% endnote %}
+
+当模板中引入子模板时（`{% raw %}{% render "foo" %}{% endraw %}`），或者调用 `.renderFile('foo')` 时，LiquidJS 会依次查看如下几个文件，并渲染第一个存在的文件：
+
+- `cwd()`/views/foo.liquid
+- `cwd()`/views/partials/foo.liquid
+
+如果上述文件都不存在，将会抛出一个 `ENOENT` 错误。
+
+{% note info 示例 %} 在 Node.js 示例中展示了怎么渲染一个文件 <a href="https://github.com/harttle/liquidjs/blob/master/demo/nodejs/" target="_blank">liquidjs/demo/nodejs/</a>。{% endnote %}
+
+在浏览器中使用 LiquidJS 时，比如当前路径为 <https://example.com/bar/index.html>，只会去 `root` 数组中的第一个路径下获取，也就是这个文件：
+
+- <https://example.com/bar/foo.liquid>
+
+如果获取失败（比如得到一个 404/500 错误）或网络错误，将会抛出一个 `ENOENT` 错误。
+
+{% note info 示例 %} 在这个示例中展示了如何从网络获取并渲染一个模板文件 <a href="https://github.com/harttle/liquidjs/blob/master/demo/browser/" target="_blank">liquidjs/demo/browser/</a>。{% endnote %}
+
+## 文件系统接口
+
+LiquidJS 定义了一个文件系统接口（[src/fs/ifs.ts][ifs]），在 Node.js 下的默认实现是 [src/fs/node.ts][fs-node]，在浏览器打包文件中的默认实现是 [src/fs/browser.ts][fs-browser]。
+你可以通过创建 `Liquid` 时的 [fs][fs] 参数来指定一个自定义实现来指定如何读取模板文件。比如从数据库里读取：
+
+```javascript
+const engine = new Liquid({
+    fs: {
+        readFileSync (file) {
+            return db.model('Template').findByIdSync(file).text
+        },
+        await readFile (file) {
+            const template = await db.model('Template').findById(file)
+            return template.text
+        },
+        existsSync () {
+            return true
+        },
+        await exists () {
+            return true
+        },
+        resolve(root, file, ext) {
+            return file
+        }
+    }
+});
+```
+
+[fs]: ../../api/interfaces/liquid_options_.liquidoptions.html#Optional-fs
+[ifs]: https://github.com/harttle/liquidjs/blob/master/src/fs/ifs.ts
+[fs-node]: https://github.com/harttle/liquidjs/blob/master/src/fs/node.ts
+[fs-browser]: https://github.com/harttle/liquidjs/blob/master/src/fs/browser.ts
+[layout]: https://help.shopify.com/en/themes/liquid/tags/theme-tags#layout
+[include]: https://help.shopify.com/themes/liquid/tags/theme-tags#include
+[renderFile]: ../../api/classes/liquid_.liquid.html#renderFile
+[renderFileSync]: ../../api/classes/liquid_.liquid.html#renderFilesync
+[parseFile]: ../../api/classes/liquid_.liquid.html#parseFile
+[parseFileSync]: ../../api/classes/liquid_.liquid.html#parseFileSync
+[root]: ../../api/interfaces/liquid_options_.liquidoptions.html#Optional-root
@@ -0,0 +1,52 @@
+---
+title: 基本语法
+---
+
+LiquidJS 语法相对简单。LiquidJS 中有两种标记：
+
+- **标签**。标签由标签名和参数构成，由 `{%raw%}{%{%endraw%}` 和 `%}` 包裹。
+- **输出**。输出由一个值和一组可选的过滤器构成，由 `{%raw%}{{{%endraw%}` 和 `}}` 包裹。
+
+## 输出
+
+**输出** 用于转换和输出变量到 HTMl。下面的模板将会把 `username` 的值插入到 input 的 `value`：
+
+```liquid
+<input type="text" name="user" value="{{username}}">
+```
+
+*输出* 里的值可以在输出之前经过若干个 **过滤器** 的转换。比如在变量后面追加一个字符串：
+
+```liquid
+{{ username | append: ", welcome to LiquidJS!" }}
+```
+
+过滤器可以级联，用起来像管道一样：
+
+```liquid
+{{ username | append: ", welcome to LiquidJS!" | capitalize }}
+```
+
+[这里](../filters/overview.html) 是 LiquidJS 支持的完整的过滤器列表。
+
+## 标签
+
+**标签** 用于控制模板渲染过程，操作模板变量，和其他模板交互等。例如 `assign` 可以用来定义一个模板中可以使用的变量：
+
+```liquid
+{% assign foo = "FOO" %}
+```
+
+一般标签成对地出现，一个开始标签和一个对应的结束标签，比如：
+
+```liquid
+{% if foo == "FOO" %}
+    Variable `foo` equals "FOO"
+{% else %}
+    Variable `foo` not equals "FOO"
+{% endif %}
+```
+
+[这里](../tags/overview.html) 是 LiquidJS 支持的完整的标签列表。
+
+[shopify/liquid]: https://github.com/Shopify/liquid
@@ -0,0 +1,27 @@
+---
+title: 真和假
+---
+
+虽然我们希望 [Liquid][sl] 是平台无关的，但 JavaScript 版本和 [Ruby 版本][ruby] 仍然有[很多区别][diff]，真值就是其中之一。
+
+## 真值表
+
+根据 [Shopify 的文档](https://shopify.github.io/liquid/basics/truthy-and-falsy/)，Ruby 版本除了 `false` 和 `nil` 之外的所有值都是真，但 JavaScript 有完全不同的类型系统，比如我们有 `undefined` 类型，以及不区分 `integer` 和 `float`，因此有些不同：
+
+value          | truthy | falsy
+---            | ---    | ---
+`true`         | ✔️      | 
+`false`        |        | ✔️
+`null`         |        | ✔️
+`undefined`    |        | ✔️
+`string`       | ✔️      |	 
+`empty string` | ✔️      |
+`0`            | ✔️      |
+`integer`	   | ✔️      |
+`float`	       | ✔️      |
+`array`        | ✔️      |
+`empty array`  | ✔️      |
+
+[ruby]: https://shopify.github.io/liquid
+[sl]: https://www.npmjs.com/package/liquidjs
+[diff]: https://github.com/harttle/liquidjs#differences-and-limitations
@@ -0,0 +1,72 @@
+---
+title: 在 Express.js 里使用
+---
+
+LiquidJS 可以用来作为 [Express 的模板引擎](https://expressjs.com/en/resources/template-engines.html)。可以把 Liquid 设置到 [view engine][express-views] 选项上即可：
+
+```javascript
+var { Liquid } = require('liquidjs');
+var engine = new Liquid();
+
+// 注册为 liquid 文件的模板引擎
+app.engine('liquid', engine.express()); 
+app.set('views', './views');            // 指定模板目录
+app.set('view engine', 'liquid');       // 把 liquid 文件设为默认模板
+```
+
+{% note info 示例 %} 这是一个在 Express.js 中使用 LiquidJS 的例子：<a href="https://github.com/harttle/liquidjs/blob/master/demo/express/" target="_blank">liquidjs/demo/express/</a>.{% endnote %}
+
+## 模板查找
+
+LiquidJS 仍然会去 [root][root] 指定的目录查找（参考 [Render A Template File][render-a-file]），也会去 Express.js 的 [`views`][express-views] 选项指定的目录里（上述例子中是 `./views`）去查找。例如你有这样的目录结构：
+
+```
+.
+├── views1/
+│ └── hello.liquid
+└── views2/
+  └── world.liquid
+```
+
+LiquidJS 的模板 root 设置到了 `views1`，Express.js 的 views 设置到了 `views2`：
+
+```javascript
+var { Liquid } = require('liquidjs');
+var engine = new Liquid({
+    root: './views1/'
+});
+
+app.engine('liquid', engine.express()); 
+app.set('views', './views2');
+app.set('view engine', 'liquid');
+```
+
+`hello.liquid` 和 `world.liquid` 两个文件都可以找到并且成功渲染：
+
+```javascript
+res.render('hello')
+res.render('world')
+```
+
+## 缓存
+
+直接把 [cache 选项][cache] 设为 `true` 即可开启模板缓存，参考 [缓存][Caching] 一文。推荐在生产环境中开启缓存，可以用如下代码：
+
+```javascript
+var { Liquid } = require('liquidjs');
+var engine = new Liquid({
+    cache: process.env.NODE_ENV === 'production'
+});
+```
+
+`cache` 还可以是一个数字表示最大缓存的模板数量，也可以是一个自定义的缓存实现，详情请参考 [cache 选项][cache]。
+
+[cache]: ../../api/interfaces/liquid_options_.liquidoptions.html#Optional-cache
+[express-views]: http://expressjs.com/en/guide/using-template-engines.html
+[parseFile]: ../../api/classes/liquid_.liquid.html#parseFile
+[parseFileSync]: ../../api/classes/liquid_.liquid.html#parseFileSync
+[layout]: https://help.shopify.com/en/themes/liquid/tags/theme-tags#layout
+[include]: https://help.shopify.com/themes/liquid/tags/theme-tags#include
+[root]: ../../api/interfaces/liquid_options_.liquidoptions.html#Optional-root
+[render-a-file]: ./render-a-file.html
+[Caching]: ./caching.html
@@ -0,0 +1,56 @@
+---
+title: 空白字符控制
+---
+
+为了让源代码缩进好看，我们会加很多空白字符比如把不会产生输出的标签也单独一行。LiquidJS 提供了空白字符控制机制，可以避免这些多余的空白字符输出到 HTML 中。
+
+## 通过标记的方式
+
+默认所有标签和输出的行，都会在行尾产生一个换行（`\n`），如果有缩进的话还会产生很多前导空格。例如：
+
+```liquid
+{%  author = "harttle" %}
+{{ author }}
+```
+
+将会输出（注意前面的空行）：
+
+```
+
+harttle
+```
+
+可以在标签和输出的标记里面加横线（`{% raw %}{{-{% endraw %}`, `-}}`, `{% raw %}{%-{% endraw %}`, `-%}`）来移除左侧/右侧的空白。例如：
+
+```liquid
+{% assign author = "harttle" -%}
+{{ author }}
+```
+
+将会输出：
+
+```
+harttle
+```
+
+这个例子中 `-%}` 移除了 `assign` 标签右侧的空白。
+
+## 通过选项
+
+此外 LiquidJS 还提供了一系列选项来帮助扫代码式地移除空白：
+
+* `trimTagLeft`
+* `trimTagRight`
+* `trimValueRight`
+* `trimValueRight`
+
+[LiquidJS][liquidjs] 默认 **不会** 移除任何空白字符，也就是说上面几个选项的默认值都为 `false`。这几个选项的详情请参考 [LiquidJS 选项][options]。
+
+## 贪婪模式
+
+上述几个设置默认情况下会跨越换行（`\n`），如果你希望保留上下空行可以把 [greedy 选项][liquidjs] 关掉，这样遇到 `\n` 就会停止。为了和 [shopify/liquid][shopify/liquid] 一致该选项默认是打开的。
+
+[shopify/liquid]: https://github.com/Shopify/liquid
+[liquidjs]: https://github.com/harttle/liquidjs
+[options]: ../../api/interfaces/liquid_options_.liquidoptions.html
+[greedy]: ../../api/interfaces/liquid_options_.liquidoptions.html#Optional-greedy