From 9ebf11edcf18969be0817dc61442e045330ef089 Mon Sep 17 00:00:00 2001 From: harttle Date: Sat, 28 Mar 2020 18:12:18 +0800 Subject: [PATCH] docs: update README to refer to liquidjs.com --- .travis.yml | 1 + README.md | 68 ++++++------------- bin/build-docs.sh | 8 ++- bin/index-docs.sh | 4 -- docs/.gitignore | 3 +- docs/package.json | 3 +- docs/source/_data/menu.yml | 2 +- docs/source/_data/sidebar.yml | 2 +- .../source/tutorials/register-filters-tags.md | 2 +- .../tutorials/{overview.md => setup.md} | 13 +--- .../zh-cn/tutorials/register-filters-tags.md | 2 +- .../zh-cn/tutorials/{overview.md => setup.md} | 11 +-- docs/themes/navy/languages/en.yml | 2 +- docs/themes/navy/languages/zh-cn.yml | 2 +- docs/themes/navy/layout/index.swig | 4 +- .../navy/layout/partial/after_footer.swig | 6 +- package.json | 6 +- 17 files changed, 50 insertions(+), 89 deletions(-) delete mode 100755 bin/index-docs.sh rename docs/source/tutorials/{overview.md => setup.md} (89%) rename docs/source/zh-cn/tutorials/{overview.md => setup.md} (88%) diff --git a/.travis.yml b/.travis.yml index 6a33cd174..e2f8532d4 100644 --- a/.travis.yml +++ b/.travis.yml @@ -25,4 +25,5 @@ jobs: deploy: skip_cleanup: true provider: pages + github_token: $GH_TOKEN local_dir: docs/public diff --git a/README.md b/README.md index e3430f941..92bceadcf 100644 --- a/README.md +++ b/README.md @@ -12,50 +12,32 @@ [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits) [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/harttle/liquidjs) -A simple, expressive, safe and [shopify][shopify/liquid] compatible template engine in pure JavaScript. -**The purpose of this repo** is to provide a standard Liquid implementation for the JavaScript community. +A simple, expressive, safe and [Shopify][shopify/liquid] compatible template engine in pure JavaScript. +**The purpose of this repo** is to provide a standard Liquid implementation for the JavaScript community so that [Jekyll sites](https://jekyllrb.com), [Github Pages](https://pages.github.com/) and [Shopify templates](https://themes.shopify.com/) can be ported to Node.js without pain. -* [Jekyll sites](https://jekyllrb.com), [Github Pages](https://pages.github.com/) and [Shopify templates](https://themes.shopify.com/) can be ported to Node.js without pain. -* All features, filters and tags in [shopify/liquid](https://github.com/Shopify/liquid) are supposed to be built in LiquidJS, though there are still some differences and limitations (see below). +* [Documentation][doc] +* Please star [LiquidJS on GitHub][github]! +* Support [LiquidJS on Open Collective][oc] or [Patreon][patreon] -> Version 9 has published, [see how to migrate to 9.0.0](https://github.com/harttle/liquidjs/wiki/Migrate-to-9)! +## Installation -## Get Started - -Install via npm: +Install from npm in Node.js: ```bash npm install --save liquidjs ``` -```javascript -var { Liquid } = require('liquidjs'); -var engine = new Liquid(); - -engine - .parseAndRender('{{name | capitalize}}', {name: 'alice'}) - .then(console.log); // outputs 'Alice' -``` - -Or include the UMD build, a live demo is available on jsfiddle: . You may need a [Promise polyfill][pp] for Node.js < 4 and ES5 browsers like [IE and Android UC][caniuse-promises]. +Or use the UMD bundle from jsDelivr: ```html - - + ``` -Also available from CLI: +More details, refer to [The Setup Guide][setup]. -```bash -echo '{{"hello" | capitalize}}' | npx liquidjs -``` +## Differences with Shopify/liquid -For detailed documents, see: - -* The [Wiki Page](https://github.com/harttle/liquidjs/wiki) contains tutorials and advanced topics. -* The [API Reference](https://harttle.github.io/liquidjs/classes/_liquid_.liquid.html) provides detailed descriptions for classes, methods and properties. - -## Differences and Limitations +All features, filters and tags in [shopify/liquid](https://github.com/Shopify/liquid) are supposed to be built in LiquidJS, but not those business-logic specific filters/tags which are typically from Shopify themes (see [Plugins List][plugins] in case you're looking for them and feel free to add yours to the list). Though being compatible the Ruby version is one of our priorities, there are still some differences: * Dynamic file locating (enabled by default), that means layout/partial names are treated as variables in liquidjs. See [#51](https://github.com/harttle/liquidjs/issues/51). * Truthy and Falsy. All values except `undefined`, `null`, `false` are truthy, whereas in Ruby Liquid all except `nil` and `false` are truthy. See [#26](https://github.com/harttle/liquidjs/pull/26). @@ -65,9 +47,6 @@ For detailed documents, see: * 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](https://shopify.github.io/liquid/filters/sort/) stability is also not defined in both shopify/liquid and LiquidJS, but it's [considered stable](https://v8.dev/features/stable-sort) for LiquidJS in Node.js 12+ and Google Chrome 70+. -Features that available on shopify website but not on shopify/liquid repo will not be implemented in this repo, -but there're some plugins available: - ## Related Packages * [gulp-liquidjs](https://www.npmjs.com/package/@tuanpham-dev/gulp-liquidjs): A shopify compatible Liquid template engine for Gulp using liquidjs. @@ -77,15 +56,13 @@ but there're some plugins available: @@ -132,13 +109,12 @@ Thanks goes to these wonderful people: -## Contribute Guideline - -* **Code Style**: , `npm run lint` to check locally. -* **Testing**: make sure test cases still pass, use `npm test` to check locally. -* **Commit Message**: align to [The Angular Commit Message Guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits), especially the [Type identifier](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#type), to allow the semantic-release bot do the work. - [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/ +[plugins]: https://liquidjs.com/tutorials/plugins.html#Plugin-List +[setup]: https://liquidjs.com/tutorials/setup.html +[doc]: https://liquidjs.com +[github]: https://github.com/harttle/liquidjs +[patreon]: https://www.patreon.com/harttle +[oc]: https://opencollective.com/liquidjs/ +[contribution]: https://liquidjs.com/tutorials/contribution-guidelines.html +[financial-support]: https://liquidjs.com/tutorials/contribution-guidelines.html#Financial-Support diff --git a/bin/build-docs.sh b/bin/build-docs.sh index 0c0c90df4..94d6b279b 100755 --- a/bin/build-docs.sh +++ b/bin/build-docs.sh @@ -1,4 +1,10 @@ #!/usr/bin/env bash ./bin/build-contributors.sh -./bin/build-apidoc.sh \ No newline at end of file +./bin/build-apidoc.sh + +cd docs +npm ci +npm run build +cp CNAME public/ +npm run index # env required: HEXO_ALGOLIA_INDEXING_KEY diff --git a/bin/index-docs.sh b/bin/index-docs.sh deleted file mode 100755 index 6d7b332e0..000000000 --- a/bin/index-docs.sh +++ /dev/null @@ -1,4 +0,0 @@ -#!/usr/bin/env bash -# env required: HEXO_ALGOLIA_INDEXING_KEY - -cd docs && hexo algolia \ No newline at end of file diff --git a/docs/.gitignore b/docs/.gitignore index edef9ab34..8c6f81f73 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -2,4 +2,5 @@ source/api/ source/zh-cn/api/ .vuepress -db.json \ No newline at end of file +db.json +public \ No newline at end of file diff --git a/docs/package.json b/docs/package.json index 89d71df62..90783d677 100644 --- a/docs/package.json +++ b/docs/package.json @@ -8,7 +8,8 @@ "scripts": { "build": "hexo generate", "start": "hexo serve", - "eslint": "eslint ." + "lint": "eslint .", + "index": "hexo algolia" }, "dependencies": { "cheerio": "^0.22.0", diff --git a/docs/source/_data/menu.yml b/docs/source/_data/menu.yml index 37819aa98..456e63797 100644 --- a/docs/source/_data/menu.yml +++ b/docs/source/_data/menu.yml @@ -1,4 +1,4 @@ -tutorials: /tutorials/overview.html +tutorials: /tutorials/setup.html tags: /tags/overview.html filters: /filters/overview.html playground: /playground.html diff --git a/docs/source/_data/sidebar.yml b/docs/source/_data/sidebar.yml index 540ecc0e4..dc6270e29 100644 --- a/docs/source/_data/sidebar.yml +++ b/docs/source/_data/sidebar.yml @@ -1,6 +1,6 @@ tutorials: getting_started: - overview: overview.html + setup: setup.html syntax: syntax.html render_file: render-file.html partials: partials-and-layouts.html diff --git a/docs/source/tutorials/register-filters-tags.md b/docs/source/tutorials/register-filters-tags.md index 28991b07c..3a9f50af8 100644 --- a/docs/source/tutorials/register-filters-tags.md +++ b/docs/source/tutorials/register-filters-tags.md @@ -5,7 +5,7 @@ title: Register Filters/Tags ## Register Tags ```javascript -// Usage: {% upper name%} +// Usage: {% upper name %} engine.registerTag('upper', { parse: function(tagToken, remainTokens) { this.str = tagToken.args; // name diff --git a/docs/source/tutorials/overview.md b/docs/source/tutorials/setup.md similarity index 89% rename from docs/source/tutorials/overview.md rename to docs/source/tutorials/setup.md index c9db105fc..26563f2a2 100644 --- a/docs/source/tutorials/overview.md +++ b/docs/source/tutorials/setup.md @@ -1,5 +1,5 @@ --- -title: Overview +title: Setup --- LiquidJS is a simple, expressive, safe and shopify compatible template engine in pure JavaScript. The purpose of this repo is to provide a standard Liquid implementation for the JavaScript community. @@ -38,16 +38,7 @@ engine ## LiquidJS in Browsers -Pre-built UMD bundles are also available and included in the npm package: - -```html - - - - -``` - -Or from jsDelivr CDN: +Pre-built UMD bundles are also available: ```html diff --git a/docs/source/zh-cn/tutorials/register-filters-tags.md b/docs/source/zh-cn/tutorials/register-filters-tags.md index 822685ff0..883ec38f2 100644 --- a/docs/source/zh-cn/tutorials/register-filters-tags.md +++ b/docs/source/zh-cn/tutorials/register-filters-tags.md @@ -5,7 +5,7 @@ title: 注册标签和过滤器 ## 注册标签 ```javascript -// 使用方式: {% upper name%} +// 使用方式: {% upper name %} engine.registerTag('upper', { parse: function(tagToken, remainTokens) { this.str = tagToken.args; // name diff --git a/docs/source/zh-cn/tutorials/overview.md b/docs/source/zh-cn/tutorials/setup.md similarity index 88% rename from docs/source/zh-cn/tutorials/overview.md rename to docs/source/zh-cn/tutorials/setup.md index 7b78bedd1..84b963f06 100644 --- a/docs/source/zh-cn/tutorials/overview.md +++ b/docs/source/zh-cn/tutorials/setup.md @@ -1,5 +1,5 @@ --- -title: 概述 +title: 安装和使用 --- LiquidJS 是一个简单的、安全的、兼容 Shopify 的、纯 JavaScript 编写的模板引擎。这个项目的目的是为 JavaScript 社区提供一个 Liquid 模板引擎的实现。 @@ -38,14 +38,7 @@ engine ## 在浏览器里使用 -LiquidJS 预先构建了 UMD 打包（包括压缩版和未压缩版），可以通过 NPM 包来使用： - -```html - - -``` - -或者直接引用 jsDelivr CDN 上的版本： +LiquidJS 预先构建了 UMD Bundle，可以通过 jsDelivr CDN 来引用： ```html diff --git a/docs/themes/navy/languages/en.yml b/docs/themes/navy/languages/en.yml index ff9d3d817..5eda57cea 100644 --- a/docs/themes/navy/languages/en.yml +++ b/docs/themes/navy/languages/en.yml @@ -30,7 +30,7 @@ page: sidebar: tutorials: getting_started: Getting Started - overview: Overview + setup: Setup syntax: Basic Syntax render_file: Render Files partials: Includes and Layouts diff --git a/docs/themes/navy/languages/zh-cn.yml b/docs/themes/navy/languages/zh-cn.yml index 9cb21b833..80a2e9980 100644 --- a/docs/themes/navy/languages/zh-cn.yml +++ b/docs/themes/navy/languages/zh-cn.yml @@ -30,7 +30,7 @@ page: sidebar: tutorials: getting_started: 开始使用 - overview: 概述 + setup: 安装和引入 syntax: 基本语法 render_file: 渲染一个文件 partials: 引用和继承 diff --git a/docs/themes/navy/layout/index.swig b/docs/themes/navy/layout/index.swig index 97ada3f7c..9eb4b72ab 100644 --- a/docs/themes/navy/layout/index.swig +++ b/docs/themes/navy/layout/index.swig @@ -2,7 +2,7 @@
@@ -33,7 +33,7 @@
  • // html === "Welcome to Liquid!"
    • diff --git a/docs/themes/navy/layout/partial/after_footer.swig b/docs/themes/navy/layout/partial/after_footer.swig index 3afadb032..7c6298541 100644 --- a/docs/themes/navy/layout/partial/after_footer.swig +++ b/docs/themes/navy/layout/partial/after_footer.swig @@ -5,14 +5,12 @@ {{ js('js/main') }} -{% if config.algolia[page.lang] %} -{% endif %} diff --git a/package.json b/package.json index ff9acd8ec..3a082d844 100644 --- a/package.json +++ b/package.json @@ -1,16 +1,13 @@ { "name": "liquidjs", "version": "9.11.7", - "description": "A simple, expressive, safe and shopify compatible template engine in pure JavaScript.", + "description": "A simple, expressive, safe and Shopify compatible template engine in pure JavaScript.", "main": "dist/liquid.cjs.js", "es2015": "dist/liquid.esm.js", "browser": "dist/liquid.js", "types": "dist/liquid.d.ts", "scripts": { "lint": "eslint .", - "build-docs": "bin/build-docs.sh", - "index-docs": "bin/index-docs.sh", - "serve-docs": "cd docs && hexo serve", "check": "npm test && npm run lint", "unit": "mocha \"test/unit/**/*.ts\"", "integration": "mocha \"test/integration/**/*.ts\"", @@ -20,6 +17,7 @@ "coverage": "nyc --reporter=html mocha \"test/{unit,integration}/**/*.ts\"", "coverage-coveralls": "nyc mocha \"test/{unit,integration}/**/*.ts\" && nyc report --reporter=text-lcov | coveralls", "build": "rollup -c rollup.config.ts && ls -lh dist", + "build-docs": "bin/build-docs.sh", "watch": "tsc --watch" }, "bin": {