Documentation updates for v5.0.0 - rebasing #1427

_basics/introduction.md

@@ -80,3 +80,12 @@ Multiple filters can be used on one output, and are applied from left to right.
 ```text
 {{ "adam!" | capitalize | prepend: "Hello " }}
 ```
+
+Filters can be categorized into various types:
+
+- <a href="#" onclick="scrollToFilter(event, 'array-filters-section')">Array filters</a>
+- <a href="#" onclick="scrollToFilter(event, 'math-filters-section')">Math filters</a>
+- <a href="#" onclick="scrollToFilter(event, 'string-filters-section')">String filters</a>
+- <a href="#" onclick="scrollToFilter(event, 'filters-section')">Other filters</a>
+
+You can see the list of filters for each type in their respective sections on the side menu.

_basics/whitespace.md

@@ -39,6 +39,8 @@ By including a hyphen in your `assign` closing delimiter, you can strip the whit
 {{ my_variable }}
 ```
 
+## Avoiding whitespace using hyphens
+
 If you don't want any of your tags to print whitespace, as a general rule you can add hyphens to both sides of all your tags (`{% raw %}{%-{% endraw %}` and `{% raw %}-%}{% endraw %}`):
 
 <p class="code-label">Input</p>
@@ -84,3 +86,24 @@ If you don't want any of your tags to print whitespace, as a general rule you ca
   Hello there!
 {%- endif %}
 ```
+
+## Avoiding whitespace without hyphens {%- include version-badge.html version="5.0.0" %}
+
+If you use the [`liquid`]({{ '/tags/template#liquid' | prepend: site.baseurl }}) tag with the `echo` keyword, you can avoid whitespace without adding hyphens throughout the Liquid code:
+
+```liquid
+{%- raw -%}
+{% liquid
+assign username = "John G. Chalmers-Smith"
+if username and username.size > 10
+  echo "Wow, " | append: username | append: ", you have a long name!"
+else
+  echo "Hello there!"
+endif
+%}
+{% endraw %}
+```
+
+## Note about the Liquid docs
+
+In the rest of the documentation, some example output text may exclude whitespace even if the corresponding input Liquid code doesn't have any hyphens. The example output is for illustrating the effects of a given tag or filter only. It shouldn't be treated as a precise output of the given input code.

_filters/abs.md

@@ -1,35 +1,23 @@
 ---
 title: abs
+category: math
 description: Liquid filter that returns the absolute value of a number.
-redirect_from: /filters/
 ---
 
-Returns the absolute value of a number.
+Returns the absolute value of a number. `abs` will also work on a string that only contains a number.
 
 <p class="code-label">Input</p>
 ```liquid
 {%- raw -%}
 {{ -17 | abs }}
 {{ 4 | abs }}
+{{ "-19.86" | abs }}
 {% endraw %}
 ```
 
 <p class="code-label">Output</p>
 ```text
 {{ -17 | abs }}
 {{ 4 | abs }}
-```
-
-`abs` will also work on a string that only contains a number.
-
-<p class="code-label">Input</p>
-```liquid
-{%- raw -%}
-{{ "-19.86" | abs }}
-{% endraw %}
-```
-
-<p class="code-label">Output</p>
-```text
 {{ "-19.86" | abs }}
 ```

_filters/append.md

@@ -1,34 +1,21 @@
 ---
 title: append
+category: string
 description: Liquid filter that appends a string to another string.
 ---
 
-Adds the specified string to the end of another string.
+Adds the specified string to the end of another string. `append` can also accept a variable as its argument.
 
 <p class="code-label">Input</p>
 ```liquid
 {%- raw -%}
 {{ "/my/fancy/url" | append: ".html" }}
+{% assign filename = "/index.html" %} {{ "website.com" | append: filename }}
 {% endraw %}
 ```
 
 <p class="code-label">Output</p>
 ```text
 {{ "/my/fancy/url" | append: ".html" }}
-```
-
-`append` can also accept a variable as its argument.
-
-<p class="code-label">Input</p>
-```liquid
-{%- raw -%}
-{% assign filename = "/index.html" %}
-{{ "website.com" | append: filename }}
-{% endraw %}
-```
-
-<p class="code-label">Output</p>
-```text
-{% assign filename = "/index.html" %}
-{{ "website.com" | append: filename }}
+{% assign filename = "/index.html" -%} {{ "website.com" | append: filename }}
 ```

_filters/at_least.md

@@ -1,5 +1,6 @@
 ---
 title: at_least
+category: math
 description: Liquid filter that limits a number to a minimum value.
 version-badge: 4.0.1
 ---
@@ -16,6 +17,6 @@ Limits a number to a minimum value.
 
 <p class="code-label">Output</p>
 ```text
-5
-4
+{{ 4 | at_least: 5 }}
+{{ 4 | at_least: 3 }}
 ```

_filters/at_most.md

@@ -1,5 +1,6 @@
 ---
 title: at_most
+category: math
 description: Liquid filter that limits a number to a maximum value.
 version-badge: 4.0.1
 ---
@@ -16,6 +17,6 @@ Limits a number to a maximum value.
 
 <p class="code-label">Output</p>
 ```text
-4
-3
+{{ 4 | at_most: 5 }}
+{{ 4 | at_most: 3 }}
 ```

_filters/capitalize.md

@@ -1,5 +1,6 @@
 ---
 title: capitalize
+category: string
 description: Liquid filter that capitalizes the first character of a string and downcases the remaining characters.
 ---
 
@@ -9,24 +10,12 @@ Makes the first character of a string capitalized and converts the remaining cha
 ```liquid
 {%- raw -%}
 {{ "title" | capitalize }}
-{% endraw %}
-```
-
-<p class="code-label">Output</p>
-```text
-{{ "title" | capitalize }}
-```
-
-Only the first character of a string is capitalized, so later words are not capitalized:
-
- <p class="code-label">Input</p>
-```liquid
-{%- raw -%}
 {{ "my GREAT title" | capitalize }}
 {% endraw %}
 ```
 
 <p class="code-label">Output</p>
 ```text
+{{ "title" | capitalize }}
 {{ "my GREAT title" | capitalize }}
 ```

_filters/ceil.md

@@ -1,16 +1,18 @@
 ---
 title: ceil
+category: math
 description: Liquid filter that returns the ceiling of a number by rounding up to the nearest integer.
 ---
 
-Rounds an input up to the nearest whole number. Liquid tries to convert the input to a number before the filter is applied.
+Rounds an input up to the nearest whole number. `ceil` will also work on a string that only contains a number.
 
 <p class="code-label">Input</p>
 ```liquid
 {%- raw -%}
 {{ 1.2 | ceil }}
 {{ 2.0 | ceil }}
 {{ 183.357 | ceil }}
+{{ "3.5" | ceil }}
 {% endraw %}
 ```
 
@@ -19,18 +21,5 @@ Rounds an input up to the nearest whole number. Liquid tries to convert the inpu
 {{ 1.2 | ceil }}
 {{ 2.0 | ceil }}
 {{ 183.357 | ceil }}
-```
-
-Here the input value is a string:
-
-<p class="code-label">Input</p>
-```liquid
-{%- raw -%}
-{{ "3.5" | ceil }}
-{% endraw %}
-```
-
-<p class="code-label">Output</p>
-```text
 {{ "3.5" | ceil }}
 ```

_filters/compact.md

@@ -1,5 +1,6 @@
 ---
 title: compact
+category: array
 description: Liquid filter that removes nil values from an array.
 version-badge: 4.0.0
 ---

_filters/concat.md

@@ -1,5 +1,6 @@
 ---
 title: concat
+category: array
 description: Liquid filter that concatenates arrays.
 version-badge: 4.0.0
 ---

_filters/date.md

@@ -1,60 +1,31 @@
 ---
 title: date
+category: aaa
 description: Liquid filter that prints and formats dates.
+redirect_from: /filters/
 ---
 
 Converts a timestamp into another date format. The format for this syntax is the same as [`strftime`](http://strftime.net). The input uses the same format as Ruby's [`Time.parse`](https://ruby-doc.org/stdlib/libdoc/time/rdoc/Time.html#method-c-parse).
 
-<p class="code-label">Input</p>
-```liquid
-{%- raw -%}
-{{ article.published_at | date: "%a, %b %d, %y" }}
-{% endraw %}
-```
-
-<p class="code-label">Output</p>
-```text
-Fri, Jul 17, 15
-```
-
-<p class="code-label">Input</p>
-```liquid
-{%- raw -%}
-{{ article.published_at | date: "%Y" }}
-{% endraw %}
-```
-
-<p class="code-label">Output</p>
-```text
-2015
-```
-
 `date` works on strings if they contain well-formatted dates.
-
-<p class="code-label">Input</p>
-```liquid
-{%- raw -%}
-{{ "March 14, 2016" | date: "%b %d, %y" }}
-{% endraw %}
-```
-
-<p class="code-label">Output</p>
-```text
-{{ "March 14, 2016" | date: "%b %d, %y" }}
-```
-
 To get the current time, pass the special word `"now"` (or `"today"`) to `date`.
 
 <p class="code-label">Input</p>
 ```liquid
 {%- raw -%}
+{{ article.published_at | date: "%a, %b %d, %y" }}
+{{ article.published_at | date: "%Y" }}
+{{ "March 14, 2016" | date: "%b %d, %y" }}
 This page was last updated at {{ "now" | date: "%Y-%m-%d %H:%M" }}.
 {% endraw %}
 ```
 
 <p class="code-label">Output</p>
 ```text
+Fri, Jul 17, 15
+2015
+{{ "March 14, 2016" | date: "%b %d, %y" }}
 This page was last updated at {{ "now" | date: "%Y-%m-%d %H:%M" }}.
 ```
 
-Note that the value will be the current time of when the page was last generated from the template, not when the page is presented to a user if caching or static site generation is involved.
+Note: If caching or static site generation is involved, the value will be the moment when the page was last generated from the template, not when the page is presented to a user.

_filters/default.md

@@ -1,54 +1,30 @@
 ---
 title: default
+category: aaa
 description: Liquid filter that specifies a fallback in case a value doesn't exist.
 ---
 
 Sets a default value for any variable with no assigned value. `default` will show its value if the input is `nil`, `false`, or empty.
 
-In this example, `product_price` is not defined, so the default value is used.
+In the following examples with a variable `product_price`:
+* When it's not defined, the default value is used.
+* When it's defined, the default value is not used.
+* When it's empty, so the default value is used.
 
 <p class="code-label">Input</p>
 ```liquid
 {%- raw -%}
 {{ product_price | default: 2.99 }}
+{% assign product_price = 4.99 %} {{ product_price | default: 2.99 }}
+{% assign product_price = "" %} {{ product_price | default: 2.99 }}
 {% endraw %}
 ```
 
 <p class="code-label">Output</p>
 ```text
 {{ product_price | default: 2.99 }}
-```
-
-In this example, `product_price` is defined, so the default value is not used.
-
-<p class="code-label">Input</p>
-```liquid
-{%- raw -%}
-{% assign product_price = 4.99 %}
-{{ product_price | default: 2.99 }}
-{% endraw %}
-```
-
-<p class="code-label">Output</p>
-```text
-{% assign product_price = 4.99 %}
-{{ product_price | default: 2.99 }}
-```
-
-In this example, `product_price` is empty, so the default value is used.
-
-<p class="code-label">Input</p>
-```liquid
-{%- raw -%}
-{% assign product_price = "" %}
-{{ product_price | default: 2.99 }}
-{% endraw %}
-```
-
-<p class="code-label">Output</p>
-```text
-{% assign product_price = "" %}
-{{ product_price | default: 2.99 }}
+{% assign product_price = 4.99 -%} {{ product_price | default: 2.99 }}
+{% assign product_price = "" -%} {{ product_price | default: 2.99 }}
 ```
 
 ### Allowing `false` {%- include version-badge.html version="5.0.0" %}
@@ -65,6 +41,5 @@ To allow variables to return `false` instead of the default value, you can use t
 
 <p class="code-label">Output</p>
 ```text
-
 false
 ```