feat: relativeReference for render/include/layout, #395

- `relativeReference` is enabled by default, set to `false` to disable
- Referenced files are still constrained within root/partias/layouts
- fix: relative filenames are not constrained (which allows arbitrary filesystem read)

Example Usage:

{% render "../foo/bar.html" %}

Note:

../foo/bar.html' should also be within `partials` (or `root` if `partials` not set)

docs/source/tutorials/options.md

@@ -23,8 +23,20 @@ It's default to `false`. When setting to `true` a default LRU cache of size 1024
 
 Additionally, it can also be a custom cache implementation. See [Caching][caching] for details.
 
+## Partials/Layouts
+
+**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.
+
+**layouts** is used to specify template directories for LiquidJS to lookup files for `{% layout %}`. Same format as `root` and will default to `root` if not specified.
+
+**partials** is used to specify template directories for LiquidJS to lookup files for `{% render %}` and `{% include %}`. Same format as `root` and will default to `root` if not specified.
+
+**relativeReference** is set to `true` by default to allow relative filenames. Note that relatively referenced files are also need to be within corresponding root. For example you can reference another file like `{% render ../foo/bar %}` as long as `../foo/bar` is also within `partials` directory.
+
 ## dynamicPartials
 
+> Note: for historical reasons, it's named dynamicPartials but it also works for layouts.
+
 **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
@@ -53,10 +65,6 @@ LiquidJS defaults this option to <code>true</code> to be compatible with shopify
 Before 2.0.1, <code>extname</code> is set to `.liquid` by default. To change that you need to set <code>extname: ''</code> explicitly. See <a href="https://github.com/harttle/liquidjs/issues/41" target="_blank">#41</a> 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.

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

@@ -15,13 +15,25 @@ const engine = new Liquid({
 下面的所有选项的概述，希望了解具体的类型和签名，请前往 <a href="https://liquidjs.com/api/interfaces/liquid_options_.liquidoptions.html" target="_self">LiquidOptions | API</a>.
 {% endnote %}
 
-## cache
+## 缓存
 
 **cache** 用来指定是否缓存曾经读取和处理过的模板来提升性能。在生产环境模板会重复渲染的情况会很有用。
 
 默认是 `false`，当设置为 `true` 时会启用一个大小为 1024 的 LRU 缓存。当然也可以传一个数字来指定缓存大小。此外还可以是一个自定义的缓存实现，LiquidJS 会通过它来查找和读写文件。详情请参考 [Caching][caching]。
 
-## dynamicPartials
+## 布局和片段
+
+**root** 用来指定 LiquidJS 查找和读取模板的根目录。可以是单个字符串，也可以是一个数组 LiquidJS 会顺序查找。详情请参考 [Render Files][render-file]。
+
+**layouts** 和 `root` 具有一样的格式，用来指定 `{% layout %}` 所使用的目录。没有指定时默认为 `root`。
+
+**partials** 和 `root` 具有一样的格式，用来指定 `{% render %}` 和 `{% include %}` 所使用的目录。没有指定时默认为 `root`。
+
+**relativeReference** 默认为 `true` 用来允许以相对路径引用其他文件。注意被引用的文件仍然需要在对应的 root 目录下。例如可以这样引用一个文件 `{% render ../foo/bar %}`，但需要确保 `../foo/bar` 处于 `partials` 目录下。
+
+## 动态引用
+
+> 注意由于历史原因这个选项叫做 dynamicPartials，但它对 layout 也起作用。
 
 **dynamicPartials** 表示是否把传给 [include][include], [render][render], [layout][layout] 标签的文件名当做变量处理。默认为 `true`。例如用上下文 `{ file: 'foo.html' }` 渲染下面的模板将会引入文件 `foo.html`：
 
@@ -51,10 +63,6 @@ LiquidJS 把这个选项默认值设为 <code>true</code> 以兼容于 shopify/l
 在 2.0.1 之前，<code>extname</code> 默认值为 `.liquid`。要禁用它需要明确设置为 <code>extname: ''</code>。详情参考 <a href="https://github.com/harttle/liquidjs/issues/41" target="_blank">#41</a>。
 {% endnote %}
 
-## root
-
-**root** 用来指定 LiquidJS 查找和读取模板的根目录。可以是单个字符串，也可以是一个数组 LiquidJS 会顺序查找。详情请参考 [Render Files][render-file]。
-
 ## fs
 
 **fs** 用来自定义文件系统实现，详情请参考 [Abstract File System][abstract-fs]。