From 5d1b63563abab6d60f8ee1a55fcfd510f606eee9 Mon Sep 17 00:00:00 2001 From: Yang Jun Date: Sun, 7 Jun 2026 13:22:08 +0800 Subject: [PATCH] docs: highlight npx in bash blocks and polish English copy Use Prism insertBefore for CLI commands like npx, tighten tutorial and reference wording, and keep YAML titles free of backticks so sidebar and page headings stay correct. Co-authored-by: Cursor --- docs/scripts/helpers.js | 2 + docs/scripts/prism-bash-extend.js | 45 ++++++++----------- docs/source/_data/sidebar.yml | 2 +- docs/source/filters/abs.md | 2 +- docs/source/filters/append.md | 2 +- .../filters/array_to_sentence_string.md | 2 +- docs/source/filters/at_least.md | 2 +- docs/source/filters/at_most.md | 2 +- docs/source/filters/base64_decode.md | 2 +- docs/source/filters/base64_encode.md | 2 +- docs/source/filters/capitalize.md | 2 +- docs/source/filters/ceil.md | 2 +- docs/source/filters/cgi_escape.md | 2 +- docs/source/filters/compact.md | 2 +- docs/source/filters/concat.md | 2 +- docs/source/filters/date.md | 12 ++--- docs/source/filters/date_to_long_string.md | 2 +- docs/source/filters/date_to_rfc822.md | 2 +- docs/source/filters/date_to_string.md | 2 +- docs/source/filters/date_to_xmlschema.md | 2 +- docs/source/filters/default.md | 2 +- docs/source/filters/divided_by.md | 2 +- docs/source/filters/downcase.md | 2 +- docs/source/filters/escape.md | 2 +- docs/source/filters/escape_once.md | 2 +- docs/source/filters/find.md | 2 +- docs/source/filters/find_exp.md | 2 +- docs/source/filters/find_index.md | 2 +- docs/source/filters/find_index_exp.md | 2 +- docs/source/filters/first.md | 2 +- docs/source/filters/floor.md | 2 +- docs/source/filters/group_by.md | 2 +- docs/source/filters/group_by_exp.md | 2 +- docs/source/filters/has.md | 2 +- docs/source/filters/has_exp.md | 2 +- docs/source/filters/hmac_sha256.md | 2 +- docs/source/filters/inspect.md | 2 +- docs/source/filters/join.md | 2 +- docs/source/filters/json.md | 4 +- docs/source/filters/jsonify.md | 2 +- docs/source/filters/last.md | 2 +- docs/source/filters/lstrip.md | 2 +- docs/source/filters/map.md | 2 +- docs/source/filters/minus.md | 2 +- docs/source/filters/modulo.md | 2 +- docs/source/filters/newline_to_br.md | 2 +- docs/source/filters/normalize_whitespace.md | 2 +- docs/source/filters/number_of_words.md | 2 +- docs/source/filters/overview.md | 2 +- docs/source/filters/plus.md | 2 +- docs/source/filters/pop.md | 2 +- docs/source/filters/prepend.md | 2 +- docs/source/filters/push.md | 2 +- docs/source/filters/raw.md | 2 +- docs/source/filters/reject.md | 2 +- docs/source/filters/reject_exp.md | 2 +- docs/source/filters/remove.md | 2 +- docs/source/filters/remove_first.md | 2 +- docs/source/filters/remove_last.md | 2 +- docs/source/filters/replace.md | 2 +- docs/source/filters/replace_first.md | 2 +- docs/source/filters/replace_last.md | 2 +- docs/source/filters/reverse.md | 2 +- docs/source/filters/round.md | 2 +- docs/source/filters/rstrip.md | 2 +- docs/source/filters/sha256.md | 2 +- docs/source/filters/shift.md | 2 +- docs/source/filters/size.md | 2 +- docs/source/filters/slice.md | 2 +- docs/source/filters/slugify.md | 2 +- docs/source/filters/sort.md | 2 +- docs/source/filters/sort_natural.md | 2 +- docs/source/filters/split.md | 2 +- docs/source/filters/strip.md | 2 +- docs/source/filters/strip_html.md | 2 +- docs/source/filters/strip_newlines.md | 2 +- docs/source/filters/sum.md | 2 +- docs/source/filters/times.md | 2 +- docs/source/filters/to_integer.md | 2 +- docs/source/filters/truncate.md | 2 +- docs/source/filters/truncatewords.md | 2 +- docs/source/filters/uniq.md | 2 +- docs/source/filters/unshift.md | 2 +- docs/source/filters/upcase.md | 2 +- docs/source/filters/uri_escape.md | 2 +- docs/source/filters/url_decode.md | 2 +- docs/source/filters/url_encode.md | 2 +- docs/source/filters/where.md | 2 +- docs/source/filters/where_exp.md | 2 +- docs/source/filters/xml_escape.md | 2 +- docs/source/tags/assign.md | 2 +- docs/source/tags/capture.md | 2 +- docs/source/tags/case.md | 2 +- docs/source/tags/cycle.md | 2 +- docs/source/tags/decrement.md | 2 +- docs/source/tags/include.md | 10 ++--- docs/source/tags/increment.md | 2 +- docs/source/tags/inline_comment.md | 2 +- docs/source/tags/layout.md | 8 ++-- docs/source/tags/overview.md | 2 +- docs/source/tags/render.md | 4 +- .../tutorials/access-scope-in-filters.md | 4 +- docs/source/tutorials/caching.md | 4 +- .../tutorials/contribution-guidelines.md | 4 +- docs/source/tutorials/differences.md | 6 +-- docs/source/tutorials/drops.md | 2 +- docs/source/tutorials/escaping.md | 6 +-- docs/source/tutorials/intro-to-liquid.md | 6 +-- docs/source/tutorials/migrate-to-9.md | 6 +-- docs/source/tutorials/operators.md | 12 ++--- docs/source/tutorials/options.md | 28 ++++++------ docs/source/tutorials/parse-parameters.md | 4 +- docs/source/tutorials/partials-and-layouts.md | 4 +- docs/source/tutorials/plugins.md | 4 +- .../source/tutorials/register-filters-tags.md | 2 +- docs/source/tutorials/render-file.md | 4 +- docs/source/tutorials/render-tag-content.md | 12 ++--- docs/source/tutorials/security-model.md | 4 +- docs/source/tutorials/setup.md | 2 +- docs/source/tutorials/static-analysis.md | 6 +-- docs/source/tutorials/sync-and-async.md | 10 ++--- docs/source/tutorials/truthy-and-falsy.md | 4 +- docs/source/tutorials/use-in-expressjs.md | 4 +- docs/source/tutorials/whitespace-control.md | 4 +- .../navy/source/css/_partial/highlight.styl | 24 +++++++--- docs/themes/navy/source/css/_variables.styl | 2 + 126 files changed, 224 insertions(+), 217 deletions(-) diff --git a/docs/scripts/helpers.js b/docs/scripts/helpers.js index e0757c87d..26d0f557e 100644 --- a/docs/scripts/helpers.js +++ b/docs/scripts/helpers.js @@ -2,6 +2,8 @@ 'use strict' +require('./prism-bash-extend') + const { resolve, basename } = require('path') const { readFileSync } = require('fs') const cheerio = require('cheerio') diff --git a/docs/scripts/prism-bash-extend.js b/docs/scripts/prism-bash-extend.js index 397f961ec..3a6cde550 100644 --- a/docs/scripts/prism-bash-extend.js +++ b/docs/scripts/prism-bash-extend.js @@ -5,7 +5,12 @@ * Hexo loads scripts from docs/scripts/ during init, before `hexo generate` * highlights fenced code via syntax_highlighter: prismjs. * - * To highlight another command, add its name to EXTRA_BASH_COMMANDS below. + * Bash highlights known commands via a large hard-coded regex (see prism-bash). + * insertBefore is the supported extension point when a command is not in that list. + * Add names to EXTRA_BASH_COMMANDS as needed. + * + * After editing this file, run `npx hexo clean` before generate/serve so + * Hexo re-highlights cached pages (db.json does not invalidate on script changes). */ const EXTRA_BASH_COMMANDS = [ 'npx' @@ -14,30 +19,16 @@ const EXTRA_BASH_COMMANDS = [ const Prism = require('prismjs') require('prismjs/components/prism-bash') -function extendBashCommandHighlighting (commands) { - const bash = Prism.languages.bash - if (!bash || !bash.function) return +const escaped = EXTRA_BASH_COMMANDS.map((cmd) => + cmd.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') +) - const fnToken = bash.function - const pattern = fnToken.pattern - if (!(pattern instanceof RegExp)) return - - const source = pattern.source - const listMatch = source.match(/\(\?:([^)]+)\)(?=\(\?\=)/) - if (!listMatch) return - - const existing = listMatch[1] - const toAdd = commands.filter((cmd) => { - const re = new RegExp(`(?:^|\\|)${cmd.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:\\||$)`) - return !re.test(existing) - }) - if (toAdd.length === 0) return - - const extended = `${existing}|${toAdd.join('|')}` - fnToken.pattern = new RegExp( - source.replace(/\(\?:([^)]+)\)(?=\(\?\=)/, `(?:${extended})`), - pattern.flags - ) -} - -extendBashCommandHighlighting(EXTRA_BASH_COMMANDS) +Prism.languages.insertBefore('bash', 'function', { + 'cli-command': { + pattern: new RegExp( + `(^|[\\s;|&]|[<>]\\()(?:${escaped.join('|')})(?=$|[)\\s;|&])` + ), + lookbehind: true, + alias: ['builtin', 'class-name'] + } +}) diff --git a/docs/source/_data/sidebar.yml b/docs/source/_data/sidebar.yml index 6edcc6b29..97f80ed26 100644 --- a/docs/source/_data/sidebar.yml +++ b/docs/source/_data/sidebar.yml @@ -114,7 +114,7 @@ filters: tags: overview: overview.html - "#": inline_comment.html + "# (inline comment)": inline_comment.html assign: assign.html capture: capture.html case: case.html diff --git a/docs/source/filters/abs.md b/docs/source/filters/abs.md index e1c7d98cc..862a3cb1c 100644 --- a/docs/source/filters/abs.md +++ b/docs/source/filters/abs.md @@ -1,5 +1,5 @@ --- -title: '`abs`' +title: Abs --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/append.md b/docs/source/filters/append.md index a67ea5449..386fe058f 100644 --- a/docs/source/filters/append.md +++ b/docs/source/filters/append.md @@ -1,5 +1,5 @@ --- -title: '`append`' +title: Append --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/array_to_sentence_string.md b/docs/source/filters/array_to_sentence_string.md index 3db10cae8..267b30390 100644 --- a/docs/source/filters/array_to_sentence_string.md +++ b/docs/source/filters/array_to_sentence_string.md @@ -1,5 +1,5 @@ --- -title: '`array_to_sentence_string`' +title: Array to sentence string --- {% since %}v10.13.0{% endsince %} diff --git a/docs/source/filters/at_least.md b/docs/source/filters/at_least.md index 29301ae15..081d979de 100644 --- a/docs/source/filters/at_least.md +++ b/docs/source/filters/at_least.md @@ -1,5 +1,5 @@ --- -title: '`at_least`' +title: At least --- {% since %}v8.4.0{% endsince %} diff --git a/docs/source/filters/at_most.md b/docs/source/filters/at_most.md index fa3f3563c..335e05a20 100644 --- a/docs/source/filters/at_most.md +++ b/docs/source/filters/at_most.md @@ -1,5 +1,5 @@ --- -title: '`at_most`' +title: At most --- {% since %}v8.4.0{% endsince %} diff --git a/docs/source/filters/base64_decode.md b/docs/source/filters/base64_decode.md index bc024b475..8276ae9af 100644 --- a/docs/source/filters/base64_decode.md +++ b/docs/source/filters/base64_decode.md @@ -1,5 +1,5 @@ --- -title: '`base64_decode`' +title: Base64 decode --- {% since %}v10.24.0{% endsince %} diff --git a/docs/source/filters/base64_encode.md b/docs/source/filters/base64_encode.md index c9445d310..85b5d4e81 100644 --- a/docs/source/filters/base64_encode.md +++ b/docs/source/filters/base64_encode.md @@ -1,5 +1,5 @@ --- -title: '`base64_encode`' +title: Base64 encode --- {% since %}v10.24.0{% endsince %} diff --git a/docs/source/filters/capitalize.md b/docs/source/filters/capitalize.md index 9f5e860e8..342d467ec 100644 --- a/docs/source/filters/capitalize.md +++ b/docs/source/filters/capitalize.md @@ -1,5 +1,5 @@ --- -title: '`capitalize`' +title: Capitalize --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/ceil.md b/docs/source/filters/ceil.md index 8439c607b..57016bd3a 100644 --- a/docs/source/filters/ceil.md +++ b/docs/source/filters/ceil.md @@ -1,5 +1,5 @@ --- -title: '`ceil`' +title: Ceil --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/cgi_escape.md b/docs/source/filters/cgi_escape.md index 56063b4c6..08ce83ec0 100644 --- a/docs/source/filters/cgi_escape.md +++ b/docs/source/filters/cgi_escape.md @@ -1,5 +1,5 @@ --- -title: '`cgi_escape`' +title: CGI escape --- {% since %}v10.13.0{% endsince %} diff --git a/docs/source/filters/compact.md b/docs/source/filters/compact.md index 83d6acc93..52031793d 100644 --- a/docs/source/filters/compact.md +++ b/docs/source/filters/compact.md @@ -1,5 +1,5 @@ --- -title: '`compact`' +title: Compact --- {% since %}v9.22.0{% endsince %} diff --git a/docs/source/filters/concat.md b/docs/source/filters/concat.md index 4c7ba9114..3702cb2dd 100644 --- a/docs/source/filters/concat.md +++ b/docs/source/filters/concat.md @@ -1,5 +1,5 @@ --- -title: '`concat`' +title: Concat --- {% since %}v2.0.0{% endsince %} diff --git a/docs/source/filters/date.md b/docs/source/filters/date.md index f03b3a824..b0bd11829 100644 --- a/docs/source/filters/date.md +++ b/docs/source/filters/date.md @@ -1,20 +1,20 @@ --- -title: '`date`' +title: Date --- {% since %}v1.9.1{% endsince %} The `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)](https://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): +* LiquidJS tries to conform to Shopify/Liquid, which uses Ruby's core [Time#strftime(string)](https://www.ruby-doc.org/core/Time.html#method-i-strftime). There are differences with [Ruby's format flags](https://ruby-doc.org/core/strftime_formatting_rdoc.html): * `%Z` (since v10.11.1) is replaced by the 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. +* Date literals are first converted to a `Date` object via [new Date()][jsDate], which means literal values are considered in the 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. * LiquidJS `date` supports locale specific weekdays and month names, which will fallback to English where `Intl` is not supported. * Ordinals (`%q`) and Jekyll specific date filters are English-only. - * [`locale`](/api/interfaces/LiquidOptions.html#locale) can be set when creating Liquid instance. Defaults to `Intl.DateTimeFormat().resolvedOptions.locale`). + * [`locale`](/api/interfaces/LiquidOptions.html#locale) can be set when creating a Liquid instance. Defaults to `Intl.DateTimeFormat().resolvedOptions().locale`. ### Examples ```liquid @@ -26,10 +26,10 @@ The `date` filter is used to convert a timestamp into the specified format. ``` # TimeZone -* During output, LiquidJS uses local timezone which can override by: +* During output, LiquidJS uses the local timezone, which can be overridden 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. + * It defaults to the runtime's timezone. * Offset can be set as, * minutes: `-360` means `'+06:00'` and `360` means `'-06:00'` * timeZone ID: `Asia/Colombo` or `America/New_York` diff --git a/docs/source/filters/date_to_long_string.md b/docs/source/filters/date_to_long_string.md index a736463b2..4aaec2f4a 100644 --- a/docs/source/filters/date_to_long_string.md +++ b/docs/source/filters/date_to_long_string.md @@ -1,5 +1,5 @@ --- -title: '`date_to_long_string`' +title: Date to long string --- {% since %}v10.13.0{% endsince %} diff --git a/docs/source/filters/date_to_rfc822.md b/docs/source/filters/date_to_rfc822.md index fd0851e3d..e207ea23a 100644 --- a/docs/source/filters/date_to_rfc822.md +++ b/docs/source/filters/date_to_rfc822.md @@ -1,5 +1,5 @@ --- -title: '`date_to_rfc822`' +title: Date to RFC822 --- {% since %}v10.13.0{% endsince %} diff --git a/docs/source/filters/date_to_string.md b/docs/source/filters/date_to_string.md index c55c4db80..1c9ff09c5 100644 --- a/docs/source/filters/date_to_string.md +++ b/docs/source/filters/date_to_string.md @@ -1,5 +1,5 @@ --- -title: '`date_to_string`' +title: Date to string --- {% since %}v10.13.0{% endsince %} diff --git a/docs/source/filters/date_to_xmlschema.md b/docs/source/filters/date_to_xmlschema.md index 730f99020..4d2993853 100644 --- a/docs/source/filters/date_to_xmlschema.md +++ b/docs/source/filters/date_to_xmlschema.md @@ -1,5 +1,5 @@ --- -title: '`date_to_xmlschema`' +title: Date to XML schema --- {% since %}v10.13.0{% endsince %} diff --git a/docs/source/filters/default.md b/docs/source/filters/default.md index b8273c60d..d6bff2d92 100644 --- a/docs/source/filters/default.md +++ b/docs/source/filters/default.md @@ -1,5 +1,5 @@ --- -title: '`default`' +title: Default --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/divided_by.md b/docs/source/filters/divided_by.md index 334a772cf..c83b6188b 100644 --- a/docs/source/filters/divided_by.md +++ b/docs/source/filters/divided_by.md @@ -1,5 +1,5 @@ --- -title: '`divided_by`' +title: Divided by --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/downcase.md b/docs/source/filters/downcase.md index f2d0a88cf..795bfe4bd 100644 --- a/docs/source/filters/downcase.md +++ b/docs/source/filters/downcase.md @@ -1,5 +1,5 @@ --- -title: '`downcase`' +title: Downcase --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/escape.md b/docs/source/filters/escape.md index 81a8fefa9..42833dd0f 100644 --- a/docs/source/filters/escape.md +++ b/docs/source/filters/escape.md @@ -1,5 +1,5 @@ --- -title: '`escape`' +title: Escape --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/escape_once.md b/docs/source/filters/escape_once.md index b7b6ef887..abc37dfdf 100644 --- a/docs/source/filters/escape_once.md +++ b/docs/source/filters/escape_once.md @@ -1,5 +1,5 @@ --- -title: '`escape_once`' +title: Escape once --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/find.md b/docs/source/filters/find.md index 02afef240..ff7113c02 100644 --- a/docs/source/filters/find.md +++ b/docs/source/filters/find.md @@ -1,5 +1,5 @@ --- -title: '`find`' +title: Find --- {% since %}v10.11.0{% endsince %} diff --git a/docs/source/filters/find_exp.md b/docs/source/filters/find_exp.md index 8fe92b7a1..1af0b45e1 100644 --- a/docs/source/filters/find_exp.md +++ b/docs/source/filters/find_exp.md @@ -1,5 +1,5 @@ --- -title: '`find_exp`' +title: Find exp --- {% since %}v10.11.0{% endsince %} diff --git a/docs/source/filters/find_index.md b/docs/source/filters/find_index.md index 5377caeb8..f3bac4497 100644 --- a/docs/source/filters/find_index.md +++ b/docs/source/filters/find_index.md @@ -1,5 +1,5 @@ --- -title: '`find_index`' +title: Find index --- {% since %}v10.21.0{% endsince %} diff --git a/docs/source/filters/find_index_exp.md b/docs/source/filters/find_index_exp.md index 5080fc4aa..3bdb12742 100644 --- a/docs/source/filters/find_index_exp.md +++ b/docs/source/filters/find_index_exp.md @@ -1,5 +1,5 @@ --- -title: '`find_index_exp`' +title: Find index exp --- {% since %}v10.21.0{% endsince %} diff --git a/docs/source/filters/first.md b/docs/source/filters/first.md index a4cc117f0..096797a38 100644 --- a/docs/source/filters/first.md +++ b/docs/source/filters/first.md @@ -1,5 +1,5 @@ --- -title: '`first`' +title: First --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/floor.md b/docs/source/filters/floor.md index 7dcfa919d..a401f3c34 100644 --- a/docs/source/filters/floor.md +++ b/docs/source/filters/floor.md @@ -1,5 +1,5 @@ --- -title: '`floor`' +title: Floor --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/group_by.md b/docs/source/filters/group_by.md index a8cd27668..980a39fec 100644 --- a/docs/source/filters/group_by.md +++ b/docs/source/filters/group_by.md @@ -1,5 +1,5 @@ --- -title: '`group_by`' +title: Group by --- {% since %}v10.11.0{% endsince %} diff --git a/docs/source/filters/group_by_exp.md b/docs/source/filters/group_by_exp.md index 82decde89..f4e7a29a3 100644 --- a/docs/source/filters/group_by_exp.md +++ b/docs/source/filters/group_by_exp.md @@ -1,5 +1,5 @@ --- -title: '`group_by_exp`' +title: Group by exp --- {% since %}v10.11.0{% endsince %} diff --git a/docs/source/filters/has.md b/docs/source/filters/has.md index e720e4d7d..219313014 100644 --- a/docs/source/filters/has.md +++ b/docs/source/filters/has.md @@ -1,5 +1,5 @@ --- -title: '`has`' +title: Has --- {% since %}v10.21.0{% endsince %} diff --git a/docs/source/filters/has_exp.md b/docs/source/filters/has_exp.md index 4b96e6184..3499e3915 100644 --- a/docs/source/filters/has_exp.md +++ b/docs/source/filters/has_exp.md @@ -1,5 +1,5 @@ --- -title: '`has_exp`' +title: Has exp --- {% since %}v10.21.0{% endsince %} diff --git a/docs/source/filters/hmac_sha256.md b/docs/source/filters/hmac_sha256.md index f1ee90678..d3c1eafc7 100644 --- a/docs/source/filters/hmac_sha256.md +++ b/docs/source/filters/hmac_sha256.md @@ -1,5 +1,5 @@ --- -title: '`hmac_sha256`' +title: HMAC SHA256 --- {% since %}vNEXT{% endsince %} diff --git a/docs/source/filters/inspect.md b/docs/source/filters/inspect.md index 2679a73a5..c48ad407b 100644 --- a/docs/source/filters/inspect.md +++ b/docs/source/filters/inspect.md @@ -1,5 +1,5 @@ --- -title: '`inspect`' +title: Inspect --- {% since %}v10.13.0{% endsince %} diff --git a/docs/source/filters/join.md b/docs/source/filters/join.md index a377c0a4f..44c3718e7 100644 --- a/docs/source/filters/join.md +++ b/docs/source/filters/join.md @@ -1,5 +1,5 @@ --- -title: '`join`' +title: Join --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/json.md b/docs/source/filters/json.md index 0366f68fe..3cd8d784d 100644 --- a/docs/source/filters/json.md +++ b/docs/source/filters/json.md @@ -1,10 +1,10 @@ --- -title: '`json`' +title: JSON --- {% since %}v9.10.0{% endsince %} -Convert values to string via `JSON.stringify()`, for debug purpose. +Convert values to string via `JSON.stringify()`, for debugging purposes. Input ```liquid diff --git a/docs/source/filters/jsonify.md b/docs/source/filters/jsonify.md index 7f2df037b..7b9a9bf78 100644 --- a/docs/source/filters/jsonify.md +++ b/docs/source/filters/jsonify.md @@ -1,5 +1,5 @@ --- -title: '`jsonify`' +title: Jsonify --- {% since %}v10.13.0{% endsince %} diff --git a/docs/source/filters/last.md b/docs/source/filters/last.md index bae7dc516..ba1b8eeb7 100644 --- a/docs/source/filters/last.md +++ b/docs/source/filters/last.md @@ -1,5 +1,5 @@ --- -title: '`last`' +title: Last --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/lstrip.md b/docs/source/filters/lstrip.md index 5e63002dc..dc0b50fc7 100644 --- a/docs/source/filters/lstrip.md +++ b/docs/source/filters/lstrip.md @@ -1,5 +1,5 @@ --- -title: '`lstrip`' +title: Lstrip --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/map.md b/docs/source/filters/map.md index b06b7d973..e69064eae 100644 --- a/docs/source/filters/map.md +++ b/docs/source/filters/map.md @@ -1,5 +1,5 @@ --- -title: '`map`' +title: Map --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/minus.md b/docs/source/filters/minus.md index a8d0f06c4..bd84ff54c 100644 --- a/docs/source/filters/minus.md +++ b/docs/source/filters/minus.md @@ -1,5 +1,5 @@ --- -title: '`minus`' +title: Minus --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/modulo.md b/docs/source/filters/modulo.md index eccb4085d..b9528ce25 100644 --- a/docs/source/filters/modulo.md +++ b/docs/source/filters/modulo.md @@ -1,5 +1,5 @@ --- -title: '`modulo`' +title: Modulo --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/newline_to_br.md b/docs/source/filters/newline_to_br.md index 199f66a21..d9f47b35a 100644 --- a/docs/source/filters/newline_to_br.md +++ b/docs/source/filters/newline_to_br.md @@ -1,5 +1,5 @@ --- -title: '`newline_to_br`' +title: Newline to br --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/normalize_whitespace.md b/docs/source/filters/normalize_whitespace.md index 02dfaeabc..54f38f272 100644 --- a/docs/source/filters/normalize_whitespace.md +++ b/docs/source/filters/normalize_whitespace.md @@ -1,5 +1,5 @@ --- -title: '`normalize_whitespace`' +title: Normalize whitespace --- {% since %}v10.13.0{% endsince %} diff --git a/docs/source/filters/number_of_words.md b/docs/source/filters/number_of_words.md index a26bc4b39..fd11e4705 100644 --- a/docs/source/filters/number_of_words.md +++ b/docs/source/filters/number_of_words.md @@ -1,5 +1,5 @@ --- -title: '`number_of_words`' +title: Number of words --- {% since %}v10.13.0{% endsince %} diff --git a/docs/source/filters/overview.md b/docs/source/filters/overview.md index 032535643..6761b7438 100644 --- a/docs/source/filters/overview.md +++ b/docs/source/filters/overview.md @@ -5,7 +5,7 @@ description: Description and demo for each Liquid filter LiquidJS implements business-logic independent filters that are typically implemented in [shopify/liquid][shopify/liquid]. This section contains the specification and demos for all the filters implemented by LiquidJS. -There's 40+ filters supported by LiquidJS. These filters can be categorized into these groups: +There are 40+ filters supported by LiquidJS. These filters can be categorized into these groups: Categories | Filters --- | --- diff --git a/docs/source/filters/plus.md b/docs/source/filters/plus.md index 9805cfe78..ae1843150 100644 --- a/docs/source/filters/plus.md +++ b/docs/source/filters/plus.md @@ -1,5 +1,5 @@ --- -title: '`plus`' +title: Plus --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/pop.md b/docs/source/filters/pop.md index afe5098a3..84271b4cb 100644 --- a/docs/source/filters/pop.md +++ b/docs/source/filters/pop.md @@ -1,5 +1,5 @@ --- -title: '`pop`' +title: Pop --- {% since %}v10.11.0{% endsince %} diff --git a/docs/source/filters/prepend.md b/docs/source/filters/prepend.md index 61e96ce5d..ed60c2827 100644 --- a/docs/source/filters/prepend.md +++ b/docs/source/filters/prepend.md @@ -1,5 +1,5 @@ --- -title: '`prepend`' +title: Prepend --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/push.md b/docs/source/filters/push.md index 386e10f7c..c2ec0dbf2 100644 --- a/docs/source/filters/push.md +++ b/docs/source/filters/push.md @@ -1,5 +1,5 @@ --- -title: '`push`' +title: Push --- {% since %}v10.8.0{% endsince %} diff --git a/docs/source/filters/raw.md b/docs/source/filters/raw.md index 61e35cd68..e45de1d8f 100644 --- a/docs/source/filters/raw.md +++ b/docs/source/filters/raw.md @@ -1,5 +1,5 @@ --- -title: '`raw`' +title: Raw --- {% since %}v9.37.0{% endsince %} diff --git a/docs/source/filters/reject.md b/docs/source/filters/reject.md index fcac7551d..0f71d97ae 100644 --- a/docs/source/filters/reject.md +++ b/docs/source/filters/reject.md @@ -1,5 +1,5 @@ --- -title: '`reject`' +title: Reject --- {% since %}v10.21.0{% endsince %} diff --git a/docs/source/filters/reject_exp.md b/docs/source/filters/reject_exp.md index 360c6f959..206b26402 100644 --- a/docs/source/filters/reject_exp.md +++ b/docs/source/filters/reject_exp.md @@ -1,5 +1,5 @@ --- -title: '`reject_exp`' +title: Reject exp --- {% since %}v10.21.0{% endsince %} diff --git a/docs/source/filters/remove.md b/docs/source/filters/remove.md index 6d55ce09e..4e60a6835 100644 --- a/docs/source/filters/remove.md +++ b/docs/source/filters/remove.md @@ -1,5 +1,5 @@ --- -title: '`remove`' +title: Remove --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/remove_first.md b/docs/source/filters/remove_first.md index 19fa1ac01..8bda8509f 100644 --- a/docs/source/filters/remove_first.md +++ b/docs/source/filters/remove_first.md @@ -1,5 +1,5 @@ --- -title: '`remove_first`' +title: Remove first --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/remove_last.md b/docs/source/filters/remove_last.md index 10fb4a6f2..e430fe54b 100644 --- a/docs/source/filters/remove_last.md +++ b/docs/source/filters/remove_last.md @@ -1,5 +1,5 @@ --- -title: '`remove_last`' +title: Remove last --- {% since %}v10.2.0{% endsince %} diff --git a/docs/source/filters/replace.md b/docs/source/filters/replace.md index 00c40718a..2d0d01631 100644 --- a/docs/source/filters/replace.md +++ b/docs/source/filters/replace.md @@ -1,5 +1,5 @@ --- -title: '`replace`' +title: Replace --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/replace_first.md b/docs/source/filters/replace_first.md index 96cb96259..8656074f5 100644 --- a/docs/source/filters/replace_first.md +++ b/docs/source/filters/replace_first.md @@ -1,5 +1,5 @@ --- -title: '`replace_first`' +title: Replace first --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/replace_last.md b/docs/source/filters/replace_last.md index fb7d14371..7103dbb55 100644 --- a/docs/source/filters/replace_last.md +++ b/docs/source/filters/replace_last.md @@ -1,5 +1,5 @@ --- -title: '`replace_last`' +title: Replace last --- {% since %}v10.2.0{% endsince %} diff --git a/docs/source/filters/reverse.md b/docs/source/filters/reverse.md index afc9ab64e..4a13c5144 100644 --- a/docs/source/filters/reverse.md +++ b/docs/source/filters/reverse.md @@ -1,5 +1,5 @@ --- -title: '`reverse`' +title: Reverse --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/round.md b/docs/source/filters/round.md index 0439994de..fbb7ffab5 100644 --- a/docs/source/filters/round.md +++ b/docs/source/filters/round.md @@ -1,5 +1,5 @@ --- -title: '`round`' +title: Round --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/rstrip.md b/docs/source/filters/rstrip.md index 80729b207..8ccdedd87 100644 --- a/docs/source/filters/rstrip.md +++ b/docs/source/filters/rstrip.md @@ -1,5 +1,5 @@ --- -title: '`rstrip`' +title: Rstrip --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/sha256.md b/docs/source/filters/sha256.md index 01b15fd33..4d584c6a5 100644 --- a/docs/source/filters/sha256.md +++ b/docs/source/filters/sha256.md @@ -1,5 +1,5 @@ --- -title: '`sha256`' +title: SHA256 --- {% since %}vNEXT{% endsince %} diff --git a/docs/source/filters/shift.md b/docs/source/filters/shift.md index 4f360d3fd..b198f477c 100644 --- a/docs/source/filters/shift.md +++ b/docs/source/filters/shift.md @@ -1,5 +1,5 @@ --- -title: '`shift`' +title: Shift --- {% since %}v10.11.0{% endsince %} diff --git a/docs/source/filters/size.md b/docs/source/filters/size.md index 600c1f0d4..20b08368d 100644 --- a/docs/source/filters/size.md +++ b/docs/source/filters/size.md @@ -1,5 +1,5 @@ --- -title: '`size`' +title: Size --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/slice.md b/docs/source/filters/slice.md index 6ad2d734f..1c6251c4b 100644 --- a/docs/source/filters/slice.md +++ b/docs/source/filters/slice.md @@ -1,5 +1,5 @@ --- -title: '`slice`' +title: Slice --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/slugify.md b/docs/source/filters/slugify.md index 88ee0c27c..06efa6618 100644 --- a/docs/source/filters/slugify.md +++ b/docs/source/filters/slugify.md @@ -1,5 +1,5 @@ --- -title: '`slugify`' +title: Slugify --- {% since %}v10.13.0{% endsince %} diff --git a/docs/source/filters/sort.md b/docs/source/filters/sort.md index 31a451138..acb8deb73 100644 --- a/docs/source/filters/sort.md +++ b/docs/source/filters/sort.md @@ -1,5 +1,5 @@ --- -title: '`sort`' +title: Sort --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/sort_natural.md b/docs/source/filters/sort_natural.md index ab908b0bc..d73a872f1 100644 --- a/docs/source/filters/sort_natural.md +++ b/docs/source/filters/sort_natural.md @@ -1,5 +1,5 @@ --- -title: '`sort_natural`' +title: Sort natural --- {% since %}v8.4.0{% endsince %} diff --git a/docs/source/filters/split.md b/docs/source/filters/split.md index b35e241be..e270008eb 100644 --- a/docs/source/filters/split.md +++ b/docs/source/filters/split.md @@ -1,5 +1,5 @@ --- -title: '`split`' +title: Split --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/strip.md b/docs/source/filters/strip.md index e778c8fce..9d0cdbfb6 100644 --- a/docs/source/filters/strip.md +++ b/docs/source/filters/strip.md @@ -1,5 +1,5 @@ --- -title: '`strip`' +title: Strip --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/strip_html.md b/docs/source/filters/strip_html.md index 571b39dd1..eb598664b 100644 --- a/docs/source/filters/strip_html.md +++ b/docs/source/filters/strip_html.md @@ -1,5 +1,5 @@ --- -title: '`strip_html`' +title: Strip HTML --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/strip_newlines.md b/docs/source/filters/strip_newlines.md index a1d49d3e1..fdbc89c19 100644 --- a/docs/source/filters/strip_newlines.md +++ b/docs/source/filters/strip_newlines.md @@ -1,5 +1,5 @@ --- -title: '`strip_newlines`' +title: Strip newlines --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/sum.md b/docs/source/filters/sum.md index a4dccacb8..1b4c02a73 100644 --- a/docs/source/filters/sum.md +++ b/docs/source/filters/sum.md @@ -1,5 +1,5 @@ --- -title: '`sum`' +title: Sum --- {% since %}v10.10.0{% endsince %} diff --git a/docs/source/filters/times.md b/docs/source/filters/times.md index 7495f0afc..fae7161af 100644 --- a/docs/source/filters/times.md +++ b/docs/source/filters/times.md @@ -1,5 +1,5 @@ --- -title: '`times`' +title: Times --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/to_integer.md b/docs/source/filters/to_integer.md index 1ea930bdc..66268d85e 100644 --- a/docs/source/filters/to_integer.md +++ b/docs/source/filters/to_integer.md @@ -1,5 +1,5 @@ --- -title: '`to_integer`' +title: To integer --- {% since %}v10.13.0{% endsince %} diff --git a/docs/source/filters/truncate.md b/docs/source/filters/truncate.md index 4e7123f5e..5761efdf3 100644 --- a/docs/source/filters/truncate.md +++ b/docs/source/filters/truncate.md @@ -1,5 +1,5 @@ --- -title: '`truncate`' +title: Truncate --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/truncatewords.md b/docs/source/filters/truncatewords.md index f35dc3764..3e523bcd7 100644 --- a/docs/source/filters/truncatewords.md +++ b/docs/source/filters/truncatewords.md @@ -1,5 +1,5 @@ --- -title: '`truncatewords`' +title: Truncatewords --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/uniq.md b/docs/source/filters/uniq.md index d2028be8e..ead1a5783 100644 --- a/docs/source/filters/uniq.md +++ b/docs/source/filters/uniq.md @@ -1,5 +1,5 @@ --- -title: '`uniq`' +title: Uniq --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/unshift.md b/docs/source/filters/unshift.md index 065582678..9cb22b66e 100644 --- a/docs/source/filters/unshift.md +++ b/docs/source/filters/unshift.md @@ -1,5 +1,5 @@ --- -title: '`unshift`' +title: Unshift --- {% since %}v10.11.0{% endsince %} diff --git a/docs/source/filters/upcase.md b/docs/source/filters/upcase.md index c55959889..66726d2c4 100644 --- a/docs/source/filters/upcase.md +++ b/docs/source/filters/upcase.md @@ -1,5 +1,5 @@ --- -title: '`upcase`' +title: Upcase --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/uri_escape.md b/docs/source/filters/uri_escape.md index c2657142d..dbb03b458 100644 --- a/docs/source/filters/uri_escape.md +++ b/docs/source/filters/uri_escape.md @@ -1,5 +1,5 @@ --- -title: '`uri_escape`' +title: URI escape --- {% since %}v10.13.0{% endsince %} diff --git a/docs/source/filters/url_decode.md b/docs/source/filters/url_decode.md index db0189ba2..85bcfe4f4 100644 --- a/docs/source/filters/url_decode.md +++ b/docs/source/filters/url_decode.md @@ -1,5 +1,5 @@ --- -title: '`url_decode`' +title: URL decode --- {% since %}v6.1.0{% endsince %} diff --git a/docs/source/filters/url_encode.md b/docs/source/filters/url_encode.md index 14379d4ce..1357bdbde 100644 --- a/docs/source/filters/url_encode.md +++ b/docs/source/filters/url_encode.md @@ -1,5 +1,5 @@ --- -title: '`url_encode`' +title: URL encode --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/filters/where.md b/docs/source/filters/where.md index b6843a0da..3c223d0f2 100644 --- a/docs/source/filters/where.md +++ b/docs/source/filters/where.md @@ -1,5 +1,5 @@ --- -title: '`where`' +title: Where --- {% since %}v8.1.0{% endsince %} diff --git a/docs/source/filters/where_exp.md b/docs/source/filters/where_exp.md index 96ba674b5..ba74f1a08 100644 --- a/docs/source/filters/where_exp.md +++ b/docs/source/filters/where_exp.md @@ -1,5 +1,5 @@ --- -title: '`where_exp`' +title: Where exp --- {% since %}v10.12.0{% endsince %} diff --git a/docs/source/filters/xml_escape.md b/docs/source/filters/xml_escape.md index 9dd048ba3..6b9e4983c 100644 --- a/docs/source/filters/xml_escape.md +++ b/docs/source/filters/xml_escape.md @@ -1,5 +1,5 @@ --- -title: '`xml_escape`' +title: XML escape --- {% since %}v10.13.0{% endsince %} diff --git a/docs/source/tags/assign.md b/docs/source/tags/assign.md index 375d583d7..abe7e57fa 100644 --- a/docs/source/tags/assign.md +++ b/docs/source/tags/assign.md @@ -1,5 +1,5 @@ --- -title: '`assign`' +title: Assign --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/tags/capture.md b/docs/source/tags/capture.md index 373991e7f..aeee5d18a 100644 --- a/docs/source/tags/capture.md +++ b/docs/source/tags/capture.md @@ -1,5 +1,5 @@ --- -title: '`capture`' +title: Capture --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/tags/case.md b/docs/source/tags/case.md index 2bac35493..0bdf4a5e0 100644 --- a/docs/source/tags/case.md +++ b/docs/source/tags/case.md @@ -4,7 +4,7 @@ title: Case {% since %}v1.9.1{% endsince %} -Creates a switch statement to compare a variable with different values. `case` initializes the switch statement, and `when` compares its values. +Creates a switch statement to compare a variable with different values. `case` initializes the switch statement, and `when` tags compare values. Input ```liquid diff --git a/docs/source/tags/cycle.md b/docs/source/tags/cycle.md index d180ded92..ec82a768f 100644 --- a/docs/source/tags/cycle.md +++ b/docs/source/tags/cycle.md @@ -1,5 +1,5 @@ --- -title: '`cycle`' +title: Cycle --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/tags/decrement.md b/docs/source/tags/decrement.md index 0a2591fd2..fdcfce9c3 100644 --- a/docs/source/tags/decrement.md +++ b/docs/source/tags/decrement.md @@ -1,5 +1,5 @@ --- -title: '`decrement`' +title: Decrement --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/tags/include.md b/docs/source/tags/include.md index 3019bb3d7..46b71460e 100644 --- a/docs/source/tags/include.md +++ b/docs/source/tags/include.md @@ -1,5 +1,5 @@ --- -title: '`include`' +title: Include --- {% since %}v1.9.1{% endsince %} @@ -22,11 +22,11 @@ If [extname][extname] option is set, the above `.liquid` extension becomes optio {% include 'footer' %} ``` -When a partial template is rendered by `include`, the code inside it can access its parent's variables but its parent cannot access variables defined inside a included template. +When a partial template is rendered by `include`, the code inside it can access its parent's variables but its parent cannot access variables defined inside an included template. ## Passing Variables -Variables defined in parent's scope can be passed to a the partial template by listing them as parameters on the `include` tag: +Variables defined in the parent's scope can be passed to the partial template by listing them as parameters on the `include` tag: ```liquid {% assign my_variable = 'apples' %} @@ -86,7 +86,7 @@ For example, the following template: {% include article.html header="HEADER" content="CONTENT" %} ``` -`article.html` with following content: +`article.html` with the following content: ```liquid
@@ -95,7 +95,7 @@ For example, the following template:
``` -Note that we're referencing the first parameter by `include.header` instead of `header`. Will output following: +Note that we're referencing the first parameter by `include.header` instead of `header`. It will output the following: ```html
diff --git a/docs/source/tags/increment.md b/docs/source/tags/increment.md index b34537b11..6e8b7e416 100644 --- a/docs/source/tags/increment.md +++ b/docs/source/tags/increment.md @@ -1,5 +1,5 @@ --- -title: '`increment`' +title: Increment --- {% since %}v1.9.1{% endsince %} diff --git a/docs/source/tags/inline_comment.md b/docs/source/tags/inline_comment.md index da3b26af1..c19771366 100644 --- a/docs/source/tags/inline_comment.md +++ b/docs/source/tags/inline_comment.md @@ -1,5 +1,5 @@ --- -title: '`#`' +title: Inline comment --- {% since %}v9.38.0{% endsince %} diff --git a/docs/source/tags/layout.md b/docs/source/tags/layout.md index 96f635867..5f53f5c18 100644 --- a/docs/source/tags/layout.md +++ b/docs/source/tags/layout.md @@ -1,5 +1,5 @@ --- -title: '`layout`' +title: Layout --- {% since %}v1.9.1{% endsince %} @@ -31,7 +31,7 @@ If [extname][extname] option is set, the `.liquid` extension becomes optional: ``` {% note info Scoping %} -When a partial template is rendered by the `layout` tag, its template have access for its caller's variables but not vice versa. Variables defined in `layout` will be popped out before control returning to its caller. +When a partial template is rendered by the `layout` tag, its template has access to its caller's variables but not vice versa. Variables defined in `layout` will be popped out before control returns to its caller. {% endnote %} ## Multiple Blocks @@ -53,7 +53,7 @@ The `layout` file can contain multiple blocks, each with a specified name. The f ## Default Block Contents -In the above `layout` files, blocks has empty contents. But it's not necessarily be empty, in which case, the block contents in `layout` files will be used as default templates. The following snippets are also equivalent to the above examples: +In the above `layout` files, blocks have empty contents. They do not necessarily need to be empty; in that case, the block contents in `layout` files will be used as default templates. The following snippets are also equivalent to the above examples: ```liquid // default-layout.liquid @@ -68,7 +68,7 @@ In the above `layout` files, blocks has empty contents. But it's not necessarily ## Passing Variables -Variables defined in current template can be passed to a the `layout` template by listing them as parameters on the `layout` tag: +Variables defined in the current template can be passed to the `layout` template by listing them as parameters on the `layout` tag: ```liquid {% assign my_variable = 'apples' %} diff --git a/docs/source/tags/overview.md b/docs/source/tags/overview.md index 6db70377a..de453a8d7 100644 --- a/docs/source/tags/overview.md +++ b/docs/source/tags/overview.md @@ -5,7 +5,7 @@ description: Description and demo for each Liquid tag LiquidJS implements business-logic independent tags that are typically implemented in [shopify/liquid][shopify/liquid]. This section contains the specification and demos for all the tags implemented by LiquidJS. -There're a dozen of tags supported by LiquidJS, with all tags in [shopify/liquid][shopify/liquid]. These tags can be categorized into these groups: +There are a dozen tags supported by LiquidJS, including all tags in [shopify/liquid][shopify/liquid]. These tags can be categorized into these groups: Category | Purpose | Tags --- | --- | --- diff --git a/docs/source/tags/render.md b/docs/source/tags/render.md index 65c8793c3..e88cc8abe 100644 --- a/docs/source/tags/render.md +++ b/docs/source/tags/render.md @@ -1,5 +1,5 @@ --- -title: '`render`' +title: Render --- {% since %}v9.2.0{% endsince %} @@ -32,7 +32,7 @@ When a partial template is rendered, the code inside it can't access its parent' ## Passing Variables -Variables defined in parent's scope can be passed to a the partial template by listing them as parameters on the `render` tag: +Variables defined in the parent's scope can be passed to the partial template by listing them as parameters on the `render` tag: ```liquid {% assign my_variable = 'apples' %} diff --git a/docs/source/tutorials/access-scope-in-filters.md b/docs/source/tutorials/access-scope-in-filters.md index b38f2db50..ffe5dc405 100644 --- a/docs/source/tutorials/access-scope-in-filters.md +++ b/docs/source/tutorials/access-scope-in-filters.md @@ -2,7 +2,7 @@ title: Access Scope in Filters --- -As covered in [Register Filters/Tags][register-filters], we can access filter arguments directly in filter function like: +As covered in [Register Filters/Tags][register-filters], we can access filter arguments directly in a filter function like: ```javascript // Usage: {{ 1 | add: 2, 3 }} @@ -10,7 +10,7 @@ As covered in [Register Filters/Tags][register-filters], we can access filter ar engine.registerFilter('add', (initial, arg1, arg2) => initial + arg1 + arg2) ``` -When it comes to stateful filters, for example transform a URL path to full URL, we'll need to access a `origin` in current scope: +When it comes to stateful filters, for example transforming a URL path to a full URL, we'll need to access an `origin` in the current scope: ```javascript // Usage: {{ '/index.html' | fullURL }} diff --git a/docs/source/tutorials/caching.md b/docs/source/tutorials/caching.md index 810103381..74e191513 100644 --- a/docs/source/tutorials/caching.md +++ b/docs/source/tutorials/caching.md @@ -2,13 +2,13 @@ title: Caching --- -In a typical website project, we'll have a directory of view templates and they'll be rendered multiple times. In production environment the template files are not likely to be changed over time (other than re-deployments). Thus it makes sense to cache the file contents and the parsed templates (in a kind of AST) to improve performance. +In a typical website project, we'll have a directory of view templates and they'll be rendered multiple times. In a production environment the template files are not likely to change over time (other than re-deployments). Thus it makes sense to cache the file contents and the parsed templates (in a kind of AST) to improve performance. LiquidJS provides multiple ways to cache the parsed templates to improve performance. ## Programmatically -The [.parse()][parse], [.parseFile()][parseFile], [.parseFileSync()][parseFileSync] APIs are used to parse templates from string or files. The result template can be then rendered multiple times with different context. +The [.parse()][parse], [.parseFile()][parseFile], [.parseFileSync()][parseFileSync] APIs are used to parse templates from strings or files. The resulting template can then be rendered multiple times with different context. Parse from string: diff --git a/docs/source/tutorials/contribution-guidelines.md b/docs/source/tutorials/contribution-guidelines.md index 5bfac1a22..d2691a88c 100644 --- a/docs/source/tutorials/contribution-guidelines.md +++ b/docs/source/tutorials/contribution-guidelines.md @@ -16,11 +16,11 @@ Getting started and building is described in [CONTRIBUTING.md](https://github.co **Commit Message**: Please align to [the Angular Commit Message Guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits), especially note the [type identifier](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#type), on which semantic-release bot depends. -**Backward-Compatibility**: please be backward-compatible. LiquidJS is used by multiple layers of softwares, including underlying libraries, compilers, site generators and Web servers. It's not easy to do a major upgrade for most of them. +**Backward-Compatibility**: please be backward-compatible. LiquidJS is used by multiple layers of software, including underlying libraries, compilers, site generators and Web servers. It's not easy to do a major upgrade for most of them. ## Financial Support -LiquidJS is Open Source and Free. To help it live and thrive, especially when LiquidJS is benefiting your business, please consider contribute on [GitHub Sponsors](https://github.com/sponsors/harttle) or [Open Collective][oc]. +LiquidJS is Open Source and Free. To help it live and thrive, especially when LiquidJS is benefiting your business, consider contributing on [GitHub Sponsors](https://github.com/sponsors/harttle) or [Open Collective][oc]. I'll add all financial contributors into [README.md](https://github.com/harttle/liquidjs#financial-support) and it'll be also shown on https://liquidjs.com after next GitHub Actions build. diff --git a/docs/source/tutorials/differences.md b/docs/source/tutorials/differences.md index cb98c08e3..7820669a3 100644 --- a/docs/source/tutorials/differences.md +++ b/docs/source/tutorials/differences.md @@ -4,7 +4,7 @@ title: Differences with Shopify/liquid ## Compatibility -Being compatible with the Ruby version is one of our priorities. Liquid language is originally [implemented in Ruby][ruby-liquid] and used by Shopify and Jekyll (and thus GitHub Pages). As you can see it's one of the most popular template engines in Ruby. There're lots of people using LiquidJS to serve their templates originally written for Shopify themes and Jekyll sites. +Being compatible with the Ruby version is one of our priorities. Liquid language is originally [implemented in Ruby][ruby-liquid] and used by Shopify and Jekyll (and thus GitHub Pages). As you can see it's one of the most popular template engines in Ruby. There are lots of people using LiquidJS to serve their templates originally written for Shopify themes and Jekyll sites. So "being compatible" means serving developers from Shopify and Jekyll well: @@ -13,8 +13,8 @@ So "being compatible" means serving developers from Shopify and Jekyll well: In the meantime, it's now implemented in JavaScript, that means it has to be more powerful: -* **Async as first-class citizen**. Filters and tags can be implemented asynchronously by return a `Promise`. -* **Also can be sync**. For scenarios that are not I/O intensive, render synchronously can be much faster. You can call synchronous APIs like `.renderSync()` as long as all the filters and tags in template support to be rendered synchronously. All builtin filters/tags support both sync and async render. +* **Async as a first-class citizen**. Filters and tags can be implemented asynchronously by returning a `Promise`. +* **Can also be synchronous**. For scenarios that are not I/O intensive, rendering synchronously can be much faster. You can call synchronous APIs like `.renderSync()` as long as all the filters and tags in the template can be rendered synchronously. All built-in filters/tags support both sync and async render. * **[Abstract file system][afs]**. Along with async feature, LiquidJS can be used to serve templates stored in Databases [#414][#414], on remote HTTP server [#485][#485], and so on. * **Additional tags and filters** like `layout` and `json`, `inspect`, `where_exp`, `group_by`, etc., see below for details. diff --git a/docs/source/tutorials/drops.md b/docs/source/tutorials/drops.md index f2ee46da3..70fa0338e 100644 --- a/docs/source/tutorials/drops.md +++ b/docs/source/tutorials/drops.md @@ -95,7 +95,7 @@ engine.parseAndRender("{{color}}", context).then(html => console.log(html)) ## toLiquid -`toLiquid()` is not a method of `Drop`, but it can be used to return a `Drop`. In cases where you have a fixed structure in the `context` that cannot change its values, you can implement `toLiquid()` to let LiquidJS use the returned value instead of itself to render the templates. +`toLiquid()` is not a method of `Drop`, but it can be used to return a `Drop`. In cases where you have a fixed structure in the `context` that cannot change its values, you can implement `toLiquid()` to let LiquidJS use the returned value instead of the object itself when rendering templates. ```javascript import { Liquid, Drop } from 'liquidjs' diff --git a/docs/source/tutorials/escaping.md b/docs/source/tutorials/escaping.md index 7bcbd03ee..ece18a9c9 100644 --- a/docs/source/tutorials/escaping.md +++ b/docs/source/tutorials/escaping.md @@ -2,10 +2,10 @@ title: Escaping --- -Escaping is important in all languages, including LiquidJS. While escaping has 2 different meanings for a template engine: +Escaping is important in all languages, including LiquidJS. Escaping has two different meanings for a template engine: 1. Escaping for the output, i.e. HTML escape. Used to escape HTML special characters so the output will not break HTML structures, aka HTML safe. -2. Escaping for the language itself, i.e. Liquid escape. Used to output strings that's considered special in Liquid language. This will be useful when you're writing an article in Liquid template to introduce Liquid language. +2. Escaping for the language itself, i.e. Liquid escape. Used to output strings that are considered special in the Liquid language. This is useful when you're writing an article in a Liquid template to introduce the Liquid language. ## HTML Escape @@ -55,7 +55,7 @@ In LiquidJS, {{ this | escape }} will be HTML-escaped, but {{{ that }}} will not. ``` -Within strings literals in LiquidJS template, `\` can be used to escape special characters in string syntax. For example: +Within string literals in a LiquidJS template, `\` can be used to escape special characters in string syntax. For example: Input ```liquid diff --git a/docs/source/tutorials/intro-to-liquid.md b/docs/source/tutorials/intro-to-liquid.md index d5baee03c..85b4d7d9a 100644 --- a/docs/source/tutorials/intro-to-liquid.md +++ b/docs/source/tutorials/intro-to-liquid.md @@ -5,7 +5,7 @@ describe: A short introduction to the Liquid template language and some simple d LiquidJS is a simple, expressive and safe [Shopify][shopify/liquid] / GitHub Pages compatible template engine in pure JavaScript. The purpose of this repo is to provide a standard Liquid implementation for the JavaScript community. Liquid is originally implemented in Ruby and used by GitHub Pages, Jekyll and Shopify, see [Differences with Shopify/liquid][diff]. -LiquidJS syntax is relatively simple. There're 2 types of markups in LiquidJS: +LiquidJS syntax is relatively simple. There are 2 types of markups in LiquidJS: - **Tags**. A tag consists of a tag name and optional arguments wrapped between `{%raw%}{%{%endraw%}` and `%}`. - **Outputs**. An output consists of a value and a list of filters, which is optional, wrapped between `{%raw%}{{{%endraw%}` and `}}`. @@ -38,7 +38,7 @@ A complete list of filters supported by LiquidJS can be found [here](../filters/ ## Tags -**Tags** are used to control the template rendering process, manipulating template variables, inter-op with other templates, etc. For example `assign` can be used to define a variable which can be later used in the template: +**Tags** are used to control the template rendering process, manipulating template variables, interacting with other templates, etc. For example `assign` can be used to define a variable that can be later used in the template: ```liquid {% assign foo = "FOO" %} @@ -50,7 +50,7 @@ Typically tags appear in pairs with a start tag and a corresponding end tag. For {% if foo == "FOO" %} Variable `foo` equals "FOO" {% else %} - Variable `foo` not equals "FOO" + Variable `foo` does not equal "FOO" {% endif %} ``` diff --git a/docs/source/tutorials/migrate-to-9.md b/docs/source/tutorials/migrate-to-9.md index 720f345a5..7d20d8602 100644 --- a/docs/source/tutorials/migrate-to-9.md +++ b/docs/source/tutorials/migrate-to-9.md @@ -2,7 +2,7 @@ title: Migrate to LiquidJS 9 --- -LiquidJS 9 has some fundamental improvements, including bugfixes, new features and performance improvement due to higher target(see #137). There're also some breaking changes. +LiquidJS 9 has some fundamental improvements, including bugfixes, new features and performance improvements due to a higher target (see #137). There are also some breaking changes. ## Features @@ -14,11 +14,11 @@ LiquidJS 9 has some fundamental improvements, including bugfixes, new features a * Rewrite boolean expression evaluation order, [#130](https://github.com/harttle/liquidjs/issues/130); * `break` and `continue` tags omitting output before them, [#123](https://github.com/harttle/liquidjs/issues/123); * Fixes errors in React.js demo during yarn install, [#145](https://github.com/harttle/liquidjs/issues/145); -* Promise typed Drops are not await-ed some times. +* Promise typed Drops are not always awaited. ## Performance -* Performance Improvements due to targeting to Node.js 8, see [#137](https://github.com/harttle/liquidjs/issues/137); +* Performance Improvements due to targeting Node.js 8, see [#137](https://github.com/harttle/liquidjs/issues/137); * Memory footprint is reduced by 57.5%, see [#202](https://github.com/harttle/liquidjs/pull/202); * Render performance is improved by 100.3%, see [#205](https://github.com/harttle/liquidjs/pull/205). diff --git a/docs/source/tutorials/operators.md b/docs/source/tutorials/operators.md index f8b5949d3..7a6358b99 100644 --- a/docs/source/tutorials/operators.md +++ b/docs/source/tutorials/operators.md @@ -2,14 +2,14 @@ title: Operators --- -LiquidJS operators are very simple and different. There're 2 types of operators supported: +LiquidJS operators are very simple and different. There are 2 types of operators supported: * Comparison operators: `==`, `!=`, `>`, `<`, `>=`, `<=` -* Logic operators: `not`, `or`, `and`, `contains` +* Logical operators: `not`, `or`, `and`, `contains` -Thus numerical operators are not supported and you cannot even plus two numbers like this `{% raw %}{{a + b}}{% endraw %}`, instead we need a filter `{% raw %}{{ a | plus: b}}{% endraw %}`. Actually `+` is a valid variable name in LiquidJS. +Thus arithmetic operators are not supported and you cannot add two numbers like this `{% raw %}{{a + b}}{% endraw %}`. Instead, use a filter: `{% raw %}{{ a | plus: b}}{% endraw %}`. Actually `+` is a valid variable name in LiquidJS. -## Logic Operators +## Logical Operators ### not @@ -59,10 +59,10 @@ Input 1. Comparison operators, and `contains`. All comparison operators alongside `contains` have the same (highest) precedence. 2. `not` operator. It has slightly more precedence than `or` and `and`. -3. `or` and `and` operators. These logic operators have the same (lowest) precedence. +3. `or` and `and` operators. These logical operators have the same (lowest) precedence. ## Associativity -Logic operators are evaluated from right to left, see [shopify docs][operator-order]. +Logical operators are evaluated from right to left, see [shopify docs][operator-order]. [operator-order]: https://shopify.dev/docs/api/liquid/basics#order-of-operations diff --git a/docs/source/tutorials/options.md b/docs/source/tutorials/options.md index f03a0a060..1fa675d0b 100644 --- a/docs/source/tutorials/options.md +++ b/docs/source/tutorials/options.md @@ -11,27 +11,27 @@ const engine = new Liquid({ }) ``` -{% note info API Document %} -Following is an overview for all the options, for exact types and signatures please refer to LiquidOptions | API. +{% note info API documentation %} +Following is an overview for all the options. For exact types and signatures, see 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. +**cache** is used to improve performance by caching previously parsed template structures, especially in cases when we 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. +It defaults to `false`. When set to `true`, a default LRU cache of size 1024 will be enabled. It can also be a number indicating the cache size you want. 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. +**root** is used to specify template directories for LiquidJS to look up and read template files. Can be a single string or 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. +**layouts** is used to specify template directories for LiquidJS to look up 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. +**partials** is used to specify template directories for LiquidJS to look up 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. +**relativeReference** is set to `true` by default to allow relative filenames. Note that relatively referenced files also need to be within the corresponding root. For example you can reference another file like `{% render ../foo/bar %}` as long as `../foo/bar` is also within `partials` directory. ## dynamicPartials @@ -62,7 +62,7 @@ LiquidJS defaults this option to true to be compatible with shopify - Use `=` instead of `:` to separate parameter key-values. - Parameters are under `include` variable instead of current scope. -For example in the following template, `name.html` is not quoted, `header` and `"HEADER"` are separated by `=`, and the `header` parameter is referenced by `include.header`. More details please check out [include][include]. +For example in the following template, `name.html` is not quoted, `header` and `"HEADER"` are separated by `=`, and the `header` parameter is referenced by `include.header`. For more details, see [include][include]. ```liquid // entry template @@ -90,7 +90,7 @@ Before 2.0.1, extname is set to `.liquid` by default. To change tha ## 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. +**fs** is used to define a custom file system implementation which will be used by LiquidJS to look up and read template files. See [Abstract File System][abstract-fs] for details. ## globals @@ -98,9 +98,9 @@ Before 2.0.1, extname is set to `.liquid` by default. To change tha ## jsTruthy -**jsTruthy** is used to use standard JavaScript truthiness rather than the Shopify. +**jsTruthy** is used to use standard JavaScript truthiness rather than Shopify's. -it defaults to false. For example, when set to true, a blank string would evaluate to false with jsTruthy. With Shopify's truthiness, a blank string is true. +It defaults to `false`. For example, when set to `true`, a blank string would evaluate to false with jsTruthy. With Shopify's truthiness, a blank string is true. ## outputEscape @@ -108,13 +108,13 @@ it defaults to false. For example, when set to true, a blank string would evalu - For untrusted output variables, set `outputEscape: "escape"` makes them be HTML escaped by default. You'll need [raw][raw] filter for direct output. - `"json"` is useful when you're using LiquidJS to create valid JSON files. -- It can even be a function which allows you to control what variables are output throughout LiquidJS. Please note the input can be any type other than string, e.g. an filter returned an non-string value. +- It can even be a function that allows you to control what variables are output throughout LiquidJS. Please note the input can be any type other than string, e.g. a filter may return a non-string value. ## Date **timezoneOffset** is used to specify a different timezone to output dates, your local timezone will be used if not specified. For example, set `timezoneOffset: 0` to output all dates in UTC/GMT 00:00. -**preserveTimezones** is a boolean effects only literal timestamps. When set to `true`, all literal timestamps will remain the same when output. This is a parser option, so Date objects passed to LiquidJS as data will not be affected. Note that `preserveTimezones` has a higher priority than `timezoneOffset`. +**preserveTimezones** is a boolean that affects only literal timestamps. When set to `true`, all literal timestamps will remain the same when output. This is a parser option, so Date objects passed to LiquidJS as data will not be affected. Note that `preserveTimezones` has a higher priority than `timezoneOffset`. **dateFormat** is used to specify a default format to output dates. `%A, %B %-e, %Y at %-l:%M %P %z` will be used if not specified. For example, set `dateFormat: %Y-%m-%dT%H:%M:%S:%LZ` to output all dates in [JavaScript Date.toJson()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toJSON) format. diff --git a/docs/source/tutorials/parse-parameters.md b/docs/source/tutorials/parse-parameters.md index dfb7c0198..ee84c46e7 100644 --- a/docs/source/tutorials/parse-parameters.md +++ b/docs/source/tutorials/parse-parameters.md @@ -4,7 +4,7 @@ title: Parse Parameters ## Access Raw Parameters -As covered in [Register Filters/Tags][register-tags], tag parameters is available on `tagToken.args` as a raw string. For example: +As covered in [Register Filters/Tags][register-tags], tag parameters are available on `tagToken.args` as a raw string. For example: ```javascript // Usage: {% random foo bar coo %} @@ -66,7 +66,7 @@ Async calls in LiquidJS are implemented by generators directly, for we can call ## Parse Key-Value Pairs as Named Parameters -Named parameters become very handy when there're optional parameters or lots of parameters, in which case the order of parameters is not important. This is exactly what [Hash][Hash] class is invented for. +Named parameters become very handy when there are optional parameters or lots of parameters, in which case the order of parameters is not important. This is exactly what the [Hash][Hash] class was invented for. ```liquid {% random from:2, to:max %} diff --git a/docs/source/tutorials/partials-and-layouts.md b/docs/source/tutorials/partials-and-layouts.md index f7be8a635..5ca92c779 100644 --- a/docs/source/tutorials/partials-and-layouts.md +++ b/docs/source/tutorials/partials-and-layouts.md @@ -25,7 +25,7 @@ color: 'red' shape: 'circle' color: 'yellow' shape: 'square' ``` -More details please refer to the [render](../tags/render.html) tag. +For more details, see the [render](../tags/render.html) tag. {% note tip The ".liquid" Extension %} The ".liquid" extension in layout, render and include can be omitted if Liquid instance is created using `extname: ".liquid"` option. See the extname option for details. @@ -54,4 +54,4 @@ My page content Footer ``` -More details please refer to the [layout](../tags/layout.html) tag. +For more details, see the [layout](../tags/layout.html) tag. diff --git a/docs/source/tutorials/plugins.md b/docs/source/tutorials/plugins.md index bb03c2ada..f7b625bac 100644 --- a/docs/source/tutorials/plugins.md +++ b/docs/source/tutorials/plugins.md @@ -6,9 +6,9 @@ A number of tags and filters can be encapsulated into a **plugin**, which will b ## Write a Plugin -A liquidjs plugin is simple function which takes the [Liquid class][liquid] as the first parameter and the Liquid instance for `this`. We can call liquidjs APIs on `this` to make certain changes, especially [register filters and tags][register]. +A LiquidJS plugin is a simple function that takes the [Liquid class][liquid] as the first parameter and uses the Liquid instance for `this`. We can call LiquidJS APIs on `this` to make certain changes, especially [register filters and tags][register]. -Now we'll make a plugin to upper case every letter of the input, save the following snippet to `upup.js`: +Now we'll make a plugin to uppercase every letter of the input. Save the following snippet to `upup.js`: ```javascript /** diff --git a/docs/source/tutorials/register-filters-tags.md b/docs/source/tutorials/register-filters-tags.md index 743029c80..2e6bf7d33 100644 --- a/docs/source/tutorials/register-filters-tags.md +++ b/docs/source/tutorials/register-filters-tags.md @@ -62,7 +62,7 @@ See existing filter implementations here: ``` -Firstly, [register][register-tags] a tag with name `wrap` and parse the content into `this.tpls`. Here in `parse(tagToken, remainTokens)`, +Firstly, [register][register-tags] a tag named `wrap` and parse the content into `this.tpls`. Here in `parse(tagToken, remainTokens)`: - `tagToken` is current token `{%raw%}{% wrap %}{%endraw%}`, and - `remainTokens` is an array of all tokens following `{%raw%}{% wrap %}{%endraw%}` until the end of this template file. -Basically, what we need to do is take/`.shift()` enough tags from `remainTokens` until we got a `endwrap` token (the name can be arbitrary, but in convention, we need it to be `endwrap`). And if there's no `endwrap` until the end of template file, we need to throw an tag-not-closed `Error`. +Basically, what we need to do is take/`.shift()` enough tags from `remainTokens` until we get an `endwrap` token (the name can be arbitrary, but by convention it should be `endwrap`). And if there's no `endwrap` until the end of the template file, we need to throw a tag-not-closed `Error`. ```javascript engine.registerTag('wrap', { @@ -57,11 +57,11 @@ engine.registerTag('wrap', { }) ``` -`.renderTemplates()` can be async, we need `yield` to wait it complete. More details on async in LiquidJS, please refer to [Sync and Async][async]. Other parts of `render()` method is quite straightforward. Here's a JSFiddle version: +`.renderTemplates()` can be async; we need `yield` to wait for it to complete. For more details on async in LiquidJS, see [Sync and Async][async]. Other parts of the `render()` method are quite straightforward. Here's a JSFiddle version: ## Using ParseStream -When it comes to complex tags like [for][for] and [if][if], the `parse()` can be very complicated. There's a [ParseStream][ParseStream] utility to organize the `parse()` in event-based style. Following is a re-written `parse()` using `ParseStream` and does exactly the same as above example. +When it comes to complex tags like [for][for] and [if][if], the `parse()` can be very complicated. There's a [ParseStream][ParseStream] utility to organize the `parse()` in event-based style. Following is a re-written `parse()` using `ParseStream` that does exactly the same as the example above. ```javascript parse(tagToken, remainTokens) { @@ -79,7 +79,7 @@ Here's a JSFiddle version: . For simplicity, t ## Manipulate the Context -The `wrap` tag above doesn't seem to be very useful, without using that tag we can render the content anyway. Now we're going to implement a `repeat` tag to render the content 2 times (we can also add a [parameter][parameter] to render arbitrary times). +The `wrap` tag above doesn't seem very useful; even without using that tag, we can render the content anyway. Now we're going to implement a `repeat` tag to render the content 2 times (we can also add a [parameter][parameter] to render an arbitrary number of times). ```liquid {% repeat %} diff --git a/docs/source/tutorials/security-model.md b/docs/source/tutorials/security-model.md index d1f0854d9..5d65a0196 100644 --- a/docs/source/tutorials/security-model.md +++ b/docs/source/tutorials/security-model.md @@ -28,7 +28,7 @@ A typical PC handles `1e8` (100M) characters without issues. ### renderLimit -Restricting template size alone is insufficient because dynamic loops with large counts can occur in render time. [renderLimit][renderLimit] mitigates this by limiting the time consumed by each `render()` call. +Restricting template size alone is insufficient because dynamic loops with large counts can occur during rendering. [renderLimit][renderLimit] mitigates this by limiting the time consumed by each `render()` call. ```liquid {%- for i in (1..10000000) -%} @@ -49,7 +49,7 @@ Render time is checked on a per-template basis (before rendering each template). In other words, `memoryLimit` limits what LiquidJS counts, not every byte your process may allocate. -Even with small number of templates and iterations, memory usage can grow exponentially. In the following example, memory doubles with each iteration: +Even with a small number of templates and iterations, memory usage can grow exponentially. In the following example, memory doubles with each iteration: ```liquid {% assign array = "1,2,3" | split: "," %} diff --git a/docs/source/tutorials/setup.md b/docs/source/tutorials/setup.md index 8a740c495..894c938f3 100644 --- a/docs/source/tutorials/setup.md +++ b/docs/source/tutorials/setup.md @@ -47,7 +47,7 @@ Pre-built UMD bundles are also available: ``` -{% note info Working Demo %} Here's a living demo on jsFiddle: jsfiddle.net/pd4jhzLs/1/, and the source code is also available in liquidjs/demo/browser/.{% endnote %} +{% note info Working Demo %} Here's a live demo on jsFiddle: jsfiddle.net/pd4jhzLs/1/, and the source code is also available in liquidjs/demo/browser/.{% endnote %} {% note warn Compatibility %} You may need a Promise polyfill for legacy browsers like IE and Android UC, see caniuse statistics. {% endnote %} diff --git a/docs/source/tutorials/static-analysis.md b/docs/source/tutorials/static-analysis.md index 86c580a39..10c38a69b 100644 --- a/docs/source/tutorials/static-analysis.md +++ b/docs/source/tutorials/static-analysis.md @@ -5,7 +5,7 @@ title: Static Template Analysis {% since %}v10.20.0{% endsince %} {% note warn Experimental %} -Note that this is an experimental feature and future APIs are subject to change. And internal structures returned can be changed w/o a major version bump. +Note that this is an experimental feature and future APIs are subject to change. Internal structures returned can be changed without a major version bump. {% endnote %} {% note info Sync and Async %} @@ -234,9 +234,9 @@ This is an example of an object returned from `Liquid.analyze()`, passing it the ### Analyzing Custom Tags -For static analysis to include results from custom tags, those tags must implement some additional methods defined on the [Template interface]( /api/interfaces/Template.html). LiquidJS will use the information returned from these methods to traverse the template and report variable usage. +For static analysis to include results from custom tags, those tags must implement some additional methods defined on the [Template interface](/api/interfaces/Template.html). LiquidJS will use the information returned from these methods to traverse the template and report variable usage. -Not all methods are required, depending in the kind of tag. If it's a block with a start tag, end tag and any amount of Liquid markup in between, it will need to implement the [`children()`](/api/interfaces/Template.html#children) method. `children()` is defined as a generator, so that we can use it in synchronous and asynchronous contexts, just like `render()`. It should return HTML content, output statements and tags that are child nodes of the current tag. +Not all methods are required, depending on the kind of tag. If it's a block with a start tag, end tag and any amount of Liquid markup in between, it will need to implement the [`children()`](/api/interfaces/Template.html#children) method. `children()` is defined as a generator, so that we can use it in synchronous and asynchronous contexts, just like `render()`. It should return HTML content, output statements and tags that are child nodes of the current tag. The [`blockScope()`](/api/interfaces/Template.html#blockScope) method is responsible for telling LiquidJS which names will be in scope for the duration of the tag's block. Some of these names could depend on the tag's arguments, and some will be fixed, like `forloop` from the `{% for %}` tag. diff --git a/docs/source/tutorials/sync-and-async.md b/docs/source/tutorials/sync-and-async.md index ce7e1f0c2..f47c48d38 100644 --- a/docs/source/tutorials/sync-and-async.md +++ b/docs/source/tutorials/sync-and-async.md @@ -2,11 +2,11 @@ title: Sync and Async --- -LiquidJS supports both sync and async evaluate, and can be used with Promises. To reuse the same set of tag/filter implementations in both sync and async, LiquidJS tags are implemented as generators. +LiquidJS supports both synchronous and asynchronous evaluation, and can be used with Promises. To reuse the same set of tag/filter implementations in both sync and async modes, LiquidJS tags are implemented as generators. ## Sync and Async API -All major methods on [Liquid][Liquid] supports both sync and async. These methods return Promises: +All major methods on [Liquid][Liquid] support both sync and async. These methods return Promises: - `render()` - `renderFile()` @@ -44,11 +44,11 @@ engine.registerTag('upper', class UpperTag extends Tag { }) ``` -All builtin tags are implemented this way and safe to use in both sync and async (I'll call it *sync-compatible*). To make your custom tag *sync-compatible*, you'll need to: +All built-in tags are implemented this way and are safe to use in both sync and async modes (I'll call it *sync-compatible*). To make your custom tag *sync-compatible*, you'll need to: - declare render function as `* render()`, in which - do not directly `return `, and -- do not call any APIs that returns a Promise. +- do not call any APIs that return a Promise. ## Call APIs that return a Promise @@ -92,7 +92,7 @@ engine.registerTag('upper', class UpperTag extends Tag { ## Async only Tags -If your tag is intend to be used only asynchronously, it can be declared as `async render()` so you can use `await` in its implementation directly: +If your tag is intended to be used only asynchronously, it can be declared as `async render()` so you can use `await` in its implementation directly: ```typescript import { toPromise, TagToken, Context, Emitter, TopLevelToken, Value, Tag, Liquid } from 'liquidjs' diff --git a/docs/source/tutorials/truthy-and-falsy.md b/docs/source/tutorials/truthy-and-falsy.md index ceeb5cadc..7451aab3c 100644 --- a/docs/source/tutorials/truthy-and-falsy.md +++ b/docs/source/tutorials/truthy-and-falsy.md @@ -2,7 +2,7 @@ title: Truthy and Falsy --- -Though [Liquid][sl] is platform-independent, there're [certain differences][diff] with [the Ruby version][ruby], one of which is the `truthy` value. +Though [Liquid][sl] is platform-independent, there are [certain differences][diff] with [the Ruby version][ruby], one of which is the `truthy` value. ## The Truth Table @@ -24,7 +24,7 @@ value | truthy | falsy ## Use JavaScript Truthy -Note that liquidjs use Shopify's truthiness by default. But it can be toggled to used standard JavaScript truthiness by setting the **jsTruthy** option to `true`. +Note that LiquidJS uses Shopify's truthiness by default. It can be toggled to use standard JavaScript truthiness by setting the **jsTruthy** option to `true`. value | truthy | falsy --- | --- | --- diff --git a/docs/source/tutorials/use-in-expressjs.md b/docs/source/tutorials/use-in-expressjs.md index 31934db12..36de03722 100644 --- a/docs/source/tutorials/use-in-expressjs.md +++ b/docs/source/tutorials/use-in-expressjs.md @@ -2,7 +2,7 @@ title: Use in Express.js --- -LiquidJS is compatible to the [express template engines](https://expressjs.com/en/resources/template-engines.html). You can set liquidjs instance to the [view engine][express-views] option: +LiquidJS is compatible with [Express template engines](https://expressjs.com/en/resources/template-engines.html). You can set the LiquidJS instance as the [view engine][express-views] option: ```javascript var { Liquid } = require('liquidjs'); @@ -50,7 +50,7 @@ res.render('world') ## Caching -Simply setting the [cache option][cache] to true will enable template caching, as explained in [Caching][Caching]. It's recommended to enable cache in production environment, which can be done by: +Simply setting the [cache option][cache] to true will enable template caching, as explained in [Caching][Caching]. It's recommended to enable cache in a production environment, which can be done by: ```javascript var { Liquid } = require('liquidjs'); diff --git a/docs/source/tutorials/whitespace-control.md b/docs/source/tutorials/whitespace-control.md index 71dc2e606..6bff3dc51 100644 --- a/docs/source/tutorials/whitespace-control.md +++ b/docs/source/tutorials/whitespace-control.md @@ -13,14 +13,14 @@ By default, all tags and output markups lines will generate a NL (`\n`), and whi {{ author }} ``` -Outputs (note the blank link): +Outputs (note the blank line): ``` harttle ``` -We can include hyphens in your tag syntax (`{% raw %}{{-{% endraw %}`, `-}}`, `{% raw %}{%-{% endraw %}`, `-%}`) to strip whitespace from left or right. For example: +You can include hyphens in tag syntax (`{% raw %}{{-{% endraw %}`, `-}}`, `{% raw %}{%-{% endraw %}`, `-%}`) to strip whitespace from the left or right. For example: ```liquid {% assign author = "harttle" -%} diff --git a/docs/themes/navy/source/css/_partial/highlight.styl b/docs/themes/navy/source/css/_partial/highlight.styl index 670436c7b..86c77609c 100644 --- a/docs/themes/navy/source/css/_partial/highlight.styl +++ b/docs/themes/navy/source/css/_partial/highlight.styl @@ -20,6 +20,9 @@ pre border: none display: block padding: 0 + &.line-numbers + white-space: pre + overflow-x: auto .highlight padding: 10px 15px @@ -101,11 +104,20 @@ pre .keyword .javascript .function color: var(--highlight-purple) - // Prism bash uses "builtin" / "class-name", not pygments-style "built_in" - .language-bash, .language-shell - .builtin - .class-name - .function - color: var(--highlight-orange) + // Prism bash: builtins (echo), external commands (npm), and cli-command (npx) + code.language-bash + .builtin, + .class-name, + .function, + .cli-command + color: var(--highlight-bash-command) + .operator + color: var(--highlight-purple) + code.language-shell + .builtin, + .class-name, + .function, + .cli-command + color: var(--highlight-bash-command) .operator color: var(--highlight-purple) diff --git a/docs/themes/navy/source/css/_variables.styl b/docs/themes/navy/source/css/_variables.styl index 61ff18e36..cac6b94fe 100644 --- a/docs/themes/navy/source/css/_variables.styl +++ b/docs/themes/navy/source/css/_variables.styl @@ -31,6 +31,7 @@ vendor-prefixes = webkit moz ms official --highlight-comment: #6e7781 --highlight-red: #cf222e --highlight-orange: #953800 + --highlight-bash-command: #c95100 --highlight-yellow: #7d4e00 --highlight-green: #116329 --highlight-aqua: #0550ae @@ -68,6 +69,7 @@ vendor-prefixes = webkit moz ms official --highlight-comment: #8b949e --highlight-red: #ff7b72 --highlight-orange: #ffa657 + --highlight-bash-command: var(--highlight-orange) --highlight-yellow: #e3b341 --highlight-green: #7ee787 --highlight-aqua: #79c0ff