diff --git a/bin/build-docs.sh b/bin/build-docs.sh
index 94d6b279b..e78ad98d4 100755
--- a/bin/build-docs.sh
+++ b/bin/build-docs.sh
@@ -7,4 +7,12 @@ cd docs
npm ci
npm run build
cp CNAME public/
-npm run index # env required: HEXO_ALGOLIA_INDEXING_KEY
+
+cp ../CHANGELOG.md source/tutorials/changelog.md
+sed -i '1i ---\ntitle: Changelog\n---\n' source/tutorials/changelog.md
+cp ../CHANGELOG.md source/zh-cn/tutorials/changelog.md
+sed -i '1i ---\ntitle: 更新日志\n---\n' source/zh-cn/tutorials/changelog.md
+
+if [ "$HEXO_ALGOLIA_INDEXING_KEY" != "" ]; then
+ npm run index
+fi
diff --git a/docs/.gitignore b/docs/.gitignore
index 8c6f81f73..4edf8b0b2 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -3,4 +3,5 @@ source/api/
source/zh-cn/api/
.vuepress
db.json
-public
\ No newline at end of file
+public
+changelog.md
\ No newline at end of file
diff --git a/docs/source/_data/news.yml b/docs/source/_data/news.yml
index 2c53efa2e..63afe7593 100644
--- a/docs/source/_data/news.yml
+++ b/docs/source/_data/news.yml
@@ -18,7 +18,7 @@
en: 'Memory Optimization: a more elaborate parser reducing the memory footprint by 57.7%.'
-
url: https://github.com/harttle/liquidjs/pull/205
- date: '2016-09-15'
+ date: '2020-09-15'
title:
zh-cn: '性能提升：引入 AST 并重新设计 Token 类型系统，使渲染性能平均提升 100.3%。'
en: 'Performance Boost: a simple AST to improve render performance by 100.3%.'
diff --git a/docs/source/_data/sidebar.yml b/docs/source/_data/sidebar.yml
index dc6270e29..3418815fb 100644
--- a/docs/source/_data/sidebar.yml
+++ b/docs/source/_data/sidebar.yml
@@ -1,7 +1,8 @@
tutorials:
getting_started:
+ intro: intro-to-liquid.html
setup: setup.html
- syntax: syntax.html
+ options: options.html
render_file: render-file.html
partials: partials-and-layouts.html
express: use-in-expressjs.html
@@ -14,6 +15,7 @@ tutorials:
truth: truthy-and-falsy.html
miscellaneous:
migration9: migrate-to-9.html
+ changelog: changelog.html
contribution_guidelines: contribution-guidelines.html
filters:
diff --git a/docs/source/index.pug b/docs/source/index.pug
index 23a934c98..0f444f7ed 100644
--- a/docs/source/index.pug
+++ b/docs/source/index.pug
@@ -8,22 +8,22 @@ ul#intro-feature-list
.intro-feature-icon
i.icon-shield
h3.intro-feature-title Safe Rendering
- p.intro-feature-desc All outputs are automatically escaped for safe and customer facing HTML rendering. Operators and expressions are parsed to AST and no #[code eval] or #[code new Function] are used.
+ p.intro-feature-desc Liquid templates are highly readable and fault-tolerant thus suitable for designers and customers. Operators and expressions are parsed to AST and no #[code eval] or #[code new Function] are used.
li.intro-feature-wrap
.intro-feature
.intro-feature-icon
- i.icon-javascript
- h3.intro-feature-title Pure JavaScript
- p.intro-feature-desc Written with zero npm dependencies and no native bindings, available for both Node.js and the browsers. All of the CMD, ESM and CJS bundles are available on CDN.
+ i.icon-rocket
+ h3.intro-feature-title Zero Dependency
+ p.intro-feature-desc Written with zero npm dependency and no native binding, available in both Node.js and browsers. All of the CMD, ESM and CJS bundles are available on CDN.
li.intro-feature-wrap
.intro-feature
.intro-feature-icon
i.icon-shopify
h3.intro-feature-title Shopify Compatible
- p.intro-feature-desc Almost all features, filters and tags from Ruby #[a(href="https://github.com/shopify/liquid") shopify/liquid] are also supported by LiquidJS. #[a(href="https://jekyllrb.com/") Jekyll sites], #[a(href="https://pages.github.com/") Github Pages] and #[a(href="https://themes.shopify.com/") Shopify templates] can be ported to Node.js without pain.
+ p.intro-feature-desc All filters and tags from Ruby #[a(href="https://github.com/shopify/liquid") shopify/liquid] are supported by LiquidJS. #[a(href="https://jekyllrb.com/") Jekyll sites], #[a(href="https://pages.github.com/") Github Pages] and #[a(href="https://themes.shopify.com/") Shopify templates] can be ported to Node.js without pain.
li.intro-feature-wrap
.intro-feature
.intro-feature-icon
- i.icon-cog
- h3.intro-feature-title Extensibility
- p.intro-feature-desc The whole repo is re-written in TypeScript strict mode to ensure the APIs are consistent and the documentation is always up to date. Apart from 60+ builtin tags and filters, LiquidJS provides APIs to register yours.
\ No newline at end of file
+ i.icon-typescript
+ h3.intro-feature-title TypeScript Strict
+ p.intro-feature-desc The whole repo is re-written in TypeScript strict mode to ensure a smooth experience using this lib and the document is precise and always up to date.
\ No newline at end of file
diff --git a/docs/source/tutorials/syntax.md b/docs/source/tutorials/intro-to-liquid.md
similarity index 100%
rename from docs/source/tutorials/syntax.md
rename to docs/source/tutorials/intro-to-liquid.md
diff --git a/docs/source/tutorials/options.md b/docs/source/tutorials/options.md
new file mode 100644
index 000000000..ac48b93bd
--- /dev/null
+++ b/docs/source/tutorials/options.md
@@ -0,0 +1,99 @@
+---
+title: Options
+---
+
+The [Liquid][liquid] constructor accepts a plain object as options to define the behaviour of LiquidJS. All of these options are optional thus we can specify any of them, for example the `cache` option:
+
+```javascript
+const { Liquid } = require('liquidjs')
+const engine = new Liquid({
+ cache: true
+})
+```
+
+{% note info API Document %}
+Following is an overview for all the options, for exact types and signatures please refer to LiquidOptions | API.
+{% endnote %}
+
+## cache
+
+**cache** is used to improve performance by caching previously parsed template structures, specially in cases when we're repeatedly parse or render files.
+
+It's default to `false`. When setting to `true` a default LRU cache of size 1024 will be enabled. And certainly it can be a number which indicates the size of cache you want.
+
+Additionally, it can also be a custom cache implementation. See [Caching][caching] for details.
+
+## dynamicPartials
+
+**dynamicPartials** indicates whether or not to treat filename arguments in [include][include], [render][render], [layout][layout] tags as a variable. Defaults to `true`. For example, render the following snippet with scope `{ file: 'foo.html' }` will include the `foo.html`:
+
+```liquid
+{% include file %}
+```
+
+Setting `dynamicPartials: false`, LiquidJS will try to include the file named `file`, which is weird but allows simpler syntax if your template relations are static:
+
+```liquid
+{% liquid foo.html %}
+```
+
+{% note warn Common Pitfall %}
+LiquidJS defaults this option to true to be compatible with shopify/liquid, but if you're from eleventy it's set to false by default (see Quoted Include Paths) which I believe is trying to be compatible with Jekyll.{% endnote %}
+
+## extname
+
+**extname** defines the default extname to be appended into filenames if the filename has no extname. Defaults to `''` which means it's disabled by default. By setting it to `.liquid`:
+
+```liquid
+{% render "foo" %} loads foo.liquid
+{% render "foo.html" %} loads foo.html
+```
+
+{% note info Legacy Versions %}
+Before 2.0.1, extname is set to `.liquid` by default. To change that you need to set extname: '' explicitly. See #41 for details.
+{% endnote %}
+
+## root
+
+**root** is used to specify template directories for LiquidJS to lookup and read template files. Can be a single string and an array of strings. See [Render Files][render-file] for details.
+
+## fs
+
+**fs** is used to define a custom file system implementation which will be used by LiquidJS to lookup and read template files. See [Abstract File System][abstract-fs] for details.
+
+## globals
+
+**globals** is used to define global variables available to all templates even in cases of [render tag][render]. See [3185][185] for details.
+
+## Trimming
+
+**greedy**, **trimOutputLeft**, **trimOutputRight**, **trimTagLeft**, **trimTagRight** options are used to eliminate extra newlines and indents in templates arround Liquid Constructs. See [Whitespace Control][wc] for details.
+
+## Delimiter
+
+**outputDelimiterLeft**, **outputDelimiterRight**, **tagDelimiterLeft**, **tagDelimiterRight** are used to customize the delimiters for LiquidJS [Tags and Filters][intro]. For example with `outputDelimiterLeft: <%=, outputDelimiterRight: %>` we are able to avoid conflicts with other languages:
+
+```ejs
+<%= username | append: ", welcome to LiquidJS!" %>
+```
+
+## Strict
+
+**strictFilters** is used to assert filter existence. If set to `false`, undefined filters will be skipped. Otherwise, undefined filters will cause a parse exception. Defaults to `false`.
+
+**strictVariables** is used to assert variable existence. If set to `false`, undefined variables will be rendered as empty string. Otherwise, undefined variables will cause a render exception. Defaults to `false`.
+
+{% note info Non-existent Tags %}
+Non-existent tags always throw errors during pasrsing and this behaviour can not be customized.
+{% endnote %}
+
+[liquid]: ../api/classes/liquid_.liquid.html
+[caching]: ./caching.html
+[abstract-fs]: ./render-file.html#Abstract-File-System
+[render-file]: ./render-file.html
+[185]: https://github.com/harttle/liquidjs/issues/185
+[render]: ../tags/render.html
+[include]: ../tags/include.html
+[layout]: ../tags/layout.html
+[wc]: ./whitespace-control.html
+[intro]: ./intro-to-liquid.html
diff --git a/docs/source/zh-cn/index.pug b/docs/source/zh-cn/index.pug
index 8c227a6d4..2a22e4ff5 100644
--- a/docs/source/zh-cn/index.pug
+++ b/docs/source/zh-cn/index.pug
@@ -8,12 +8,12 @@ ul#intro-feature-list
.intro-feature-icon
i.icon-shield
h3.intro-feature-title 安全渲染
- p.intro-feature-desc 所有输出都默认经过转义，可以安全地开放给客户使用。运算符和表达式都先解析到 AST 再去渲染，避免了 #[code eval] 和 #[code new Function]。
+ p.intro-feature-desc Liquid 模板有很强的可读性和容错性，适用于开放给设计师和客户。运算符和表达式都先解析到 AST 再去渲染，避免了 #[code eval] 和 #[code new Function]。
li.intro-feature-wrap
.intro-feature
.intro-feature-icon
- i.icon-javascript
- h3.intro-feature-title 纯 JavaScript
+ i.icon-rocket
+ h3.intro-feature-title 零依赖
p.intro-feature-desc 零 NPM 依赖且没有 Native 绑定的 Liquid 实现，Node.js 和浏览器通用。同时提供了 CDN 可用的 CMD, ESM 和 CJS 打包。
li.intro-feature-wrap
.intro-feature
@@ -24,6 +24,6 @@ ul#intro-feature-list
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 来注册你自己的插件。
+ i.icon-typescript
+ h3.intro-feature-title TypeScript
+ p.intro-feature-desc 整个项目在 TypeScript strict 模式下重写，让这个库拥有顺滑的使用体验，同时确保了一致的 API 和实时的、精确的文档。
diff --git a/docs/source/zh-cn/tutorials/syntax.md b/docs/source/zh-cn/tutorials/intro-to-liquid.md
similarity index 100%
rename from docs/source/zh-cn/tutorials/syntax.md
rename to docs/source/zh-cn/tutorials/intro-to-liquid.md
diff --git a/docs/source/zh-cn/tutorials/options.md b/docs/source/zh-cn/tutorials/options.md
new file mode 100644
index 000000000..5a664bfa0
--- /dev/null
+++ b/docs/source/zh-cn/tutorials/options.md
@@ -0,0 +1,97 @@
+---
+title: 选项
+---
+
+[Liquid][liquid] 构造函数接受一个参数对象，用来定义各种模板引擎行为。这些参数都是可选的，比如我可以指定其中一个参数 `cache`：
+
+```javascript
+const { Liquid } = require('liquidjs')
+const engine = new Liquid({
+ cache: true
+})
+```
+
+{% note info API 文档 %}
+下面的所有选项的概述，希望了解具体的类型和签名，请前往 LiquidOptions | API.
+{% endnote %}
+
+## cache
+
+**cache** 用来指定是否缓存曾经读取和处理过的模板来提升性能。在生产环境模板会重复渲染的情况会很有用。
+
+默认是 `false`，当设置为 `true` 时会启用一个大小为 1024 的 LRU 缓存。当然也可以传一个数字来指定缓存大小。此外还可以是一个自定义的缓存实现，LiquidJS 会通过它来查找和读写文件。详情请参考 [Caching][caching]。
+
+## dynamicPartials
+
+**dynamicPartials** 表示是否把传给 [include][include], [render][render], [layout][layout] 标签的文件名当做变量处理。默认为 `true`。例如用上下文 `{ file: 'foo.html' }` 渲染下面的模板将会引入文件 `foo.html`：
+
+```liquid
+{% include file %}
+```
+
+设置 `dynamicPartials: false` 后 LiquidJS 将会尝试去读取 `file`。当你的模板之间都是静态引入关系时会很有用：
+
+```liquid
+{% liquid foo.html %}
+```
+
+{% note warn Common Pitfall %}
+LiquidJS 把这个选项默认值设为 true 以兼容于 shopify/liquid，但如果你在使用 eleventy 它会设置默认值 false （参考 Quoted Include Paths）以兼容于 Jekyll。{% endnote %}
+
+## extname
+
+**extname** 定义了默认的文件后缀，当传入文件名不包含后缀时自动追加。默认值是 `''` 也就是说默认是禁用的。如果设置为 `.liquid`：
+
+```liquid
+{% render "foo" %} 会加载 foo.liquid
+{% render "foo.html" %} 会加载 foo.html
+```
+
+{% note info Legacy Versions %}
+在 2.0.1 之前，extname 默认值为 `.liquid`。要禁用它需要明确设置为 extname: ''。详情参考 #41。
+{% endnote %}
+
+## root
+
+**root** 用来指定 LiquidJS 查找和读取模板的根目录。可以是单个字符串，也可以是一个数组 LiquidJS 会顺序查找。详情请参考 [Render Files][render-file]。
+
+## fs
+
+**fs** 用来自定义文件系统实现，详情请参考 [Abstract File System][abstract-fs]。
+
+## globals
+
+**globals** 用来定义对所有模板可见的全局变量。包括 [render tag][render] 引入的子模板，见 [3185][185]。
+
+## 换行和缩进
+
+**greedy**, **trimOutputLeft**, **trimOutputRight**, **trimTagLeft**, **trimTagRight** 选项用来移除 Liquid 语法周围的换行和缩进，详情请参考 [Whitespace Control][wc]。
+
+## 自定义分隔符
+
+**outputDelimiterLeft**, **outputDelimiterRight**, **tagDelimiterLeft**, **tagDelimiterRight** 用来自定义 LiquidJS 中 [标签和过滤器][intro] 的分隔符。例如设置了 `outputDelimiterLeft: <%=, outputDelimiterRight: %>` 后我们可以避免跟其他模板引擎冲突：
+
+```ejs
+<%= username | append: ", welcome to LiquidJS!" %>
+```
+
+## 严格模式
+
+**strictFilters** 用来启用过滤器的严格模式，如果设置为 `true` 过滤器不存在时解析会抛出异常。默认为 `false`，这时会跳过不存在的过滤器。
+
+**strictVariables** 用来启用变量严格模式。如果设置为 `true` 变量不存在时渲染会抛出异常，默认为 `false` 这时不存在的变量会被渲染为空字符串。
+
+{% note info 不存在的标签 %}
+不存在的标签总是会抛出一个解析异常，这一行为无法自定义。
+{% endnote %}
+
+[liquid]: ../api/classes/liquid_.liquid.html
+[caching]: ./caching.html
+[abstract-fs]: ./render-file.html#Abstract-File-System
+[render-file]: ./render-file.html
+[185]: https://github.com/harttle/liquidjs/issues/185
+[render]: ../tags/render.html
+[include]: ../tags/include.html
+[layout]: ../tags/layout.html
+[wc]: ./whitespace-control.html
+[intro]: ./intro-to-liquid.html
diff --git a/docs/themes/navy/languages/en.yml b/docs/themes/navy/languages/en.yml
index 5eda57cea..9c0775708 100644
--- a/docs/themes/navy/languages/en.yml
+++ b/docs/themes/navy/languages/en.yml
@@ -30,8 +30,9 @@ page:
sidebar:
tutorials:
getting_started: Getting Started
+ intro: Intro to Liquid
setup: Setup
- syntax: Basic Syntax
+ options: Options
render_file: Render Files
partials: Includes and Layouts
express: Use in Express.js
@@ -47,6 +48,7 @@ sidebar:
miscellaneous: Miscellaneous
migration9: 'Migrate to LiquidJS 9'
contribution_guidelines: 'Contribution Guidelines'
+ changelog: 'Changelog'
filters:
overview: Overview
tags:
diff --git a/docs/themes/navy/languages/zh-cn.yml b/docs/themes/navy/languages/zh-cn.yml
index 80a2e9980..991e3e263 100644
--- a/docs/themes/navy/languages/zh-cn.yml
+++ b/docs/themes/navy/languages/zh-cn.yml
@@ -30,16 +30,17 @@ page:
sidebar:
tutorials:
getting_started: 开始使用
- setup: 安装和引入
- syntax: 基本语法
- render_file: 渲染一个文件
- partials: 引用和继承
- express: 在 Express.js 里使用
+ intro: Liquid 简介
+ setup: 安装
+ options: 选项
+ render_file: 文件渲染
+ partials: 引用/继承
+ express: Express.js 中使用
advanced: 高级主题
caching: 缓存
registeration: 注册标签/过滤器
- whitespace: 空白字符控制
+ whitespace: 换行和缩进
plugins: 插件
operators: 运算符
truth: 真和假
@@ -47,6 +48,7 @@ sidebar:
miscellaneous: 其他
migration9: '迁移到 LiquidJS 9'
contribution_guidelines: '贡献指南'
+ changelog: '更新日志'
filters:
overview: 概述
tags:
diff --git a/docs/themes/navy/source/css/_partial/icomoon.css b/docs/themes/navy/source/css/_partial/icomoon.css
index beb6523f8..4df37049f 100644
--- a/docs/themes/navy/source/css/_partial/icomoon.css
+++ b/docs/themes/navy/source/css/_partial/icomoon.css
@@ -31,9 +31,6 @@ i {
.icon-network:before {
content: "\e902";
}
-.icon-javascript:before {
- content: "\e901";
-}
.icon-opencollective:before {
content: "\e903";
}
@@ -43,9 +40,6 @@ i {
.icon-search:before {
content: "\f002";
}
-.icon-cog:before {
- content: "\f013";
-}
.icon-gear:before {
content: "\f013";
}
@@ -70,3 +64,9 @@ i {
.icon-shield:before {
content: "\f132";
}
+.icon-rocket:before {
+ content: "\e9a5";
+}
+.icon-typescript:before {
+ content: "\e900";
+}
diff --git a/docs/themes/navy/source/css/_partial/page.styl b/docs/themes/navy/source/css/_partial/page.styl
index 669f967d0..001decb14 100644
--- a/docs/themes/navy/source/css/_partial/page.styl
+++ b/docs/themes/navy/source/css/_partial/page.styl
@@ -50,7 +50,7 @@ note-warn = hsl(0, 100%, 50%)
overflow-y: auto
#article-toc-top
- margin-top: 10px
+ margin-top: 13px
font-size: 0.9em
text-decoration: none
color: color-default
@@ -134,6 +134,14 @@ note-warn = hsl(0, 100%, 50%)
&:after
content: " (" attr(href) ")"
font-size: 80%
+ &[target="_blank"]
+ position: relative
+ &::after
+ content: '\00f08e'
+ font-family: 'icomoon'
+ padding-left: 3px;
+ vertical-align: super;
+ zoom: .7
strong
font-weight: bold
em
@@ -180,10 +188,12 @@ note-warn = hsl(0, 100%, 50%)
&.warn
border-left-color: note-warn
.note-title
- margin: 1em 0
+ margin: 1em 0 0.5em
display: block
font-size: 1.3em
font-weight: bold
+ + *
+ margin-top: 0
table
max-width: 100%
border: 1px solid color-border
diff --git a/docs/themes/navy/source/fonts/icomoon.eot b/docs/themes/navy/source/fonts/icomoon.eot
index 0f9869124..1d79414ef 100644
Binary files a/docs/themes/navy/source/fonts/icomoon.eot and b/docs/themes/navy/source/fonts/icomoon.eot differ
diff --git a/docs/themes/navy/source/fonts/icomoon.svg b/docs/themes/navy/source/fonts/icomoon.svg
index 52dea1492..7b1bd4351 100644
--- a/docs/themes/navy/source/fonts/icomoon.svg
+++ b/docs/themes/navy/source/fonts/icomoon.svg
@@ -7,17 +7,18 @@
-
+
+
-
+
diff --git a/docs/themes/navy/source/fonts/icomoon.ttf b/docs/themes/navy/source/fonts/icomoon.ttf
index fe215d5fd..7ed8d3585 100644
Binary files a/docs/themes/navy/source/fonts/icomoon.ttf and b/docs/themes/navy/source/fonts/icomoon.ttf differ
diff --git a/docs/themes/navy/source/fonts/icomoon.woff b/docs/themes/navy/source/fonts/icomoon.woff
index 9f5126ecb..61b32bfec 100644
Binary files a/docs/themes/navy/source/fonts/icomoon.woff and b/docs/themes/navy/source/fonts/icomoon.woff differ
diff --git a/src/liquid-options.ts b/src/liquid-options.ts
index 46232e790..eec218ee2 100644
--- a/src/liquid-options.ts
+++ b/src/liquid-options.ts
@@ -13,9 +13,9 @@ export interface LiquidOptions {
cache?: boolean | number | Cache;
/** If set, treat the `filepath` parameter in `{%include filepath %}` and `{%layout filepath%}` as a variable, otherwise as a literal value. Defaults to `true`. */
dynamicPartials?: boolean;
- /** Enable strict filter existence. If set to `false`, undefined filters will be rendered as empty string. Otherwise, undefined filters will cause an exception. Defaults to `false`. */
+ /** Whether or not to assert filter existence. If set to `false`, undefined filters will be skipped. Otherwise, undefined filters will cause an exception. Defaults to `false`. */
strictFilters?: boolean;
- /** Enable strict variable derivation. If set to `false`, undefined variables will be rendered as empty string. Otherwise, undefined variables will cause an exception. Defaults to `false`. */
+ /** Whether or not to assert variable existence. If set to `false`, undefined variables will be rendered as empty string. Otherwise, undefined variables will cause an exception. Defaults to `false`. */
strictVariables?: boolean;
/** Strip blank characters (including ` `, `\t`, and `\r`) from the right of tags (`{% %}`) until `\n` (inclusive). Defaults to `false`. */
trimTagRight?: boolean;