Improve documentation for available filters

Replaces #37

config/toc-markup.yaml

@@ -2,6 +2,7 @@ Markup:
   icon: "icon-code"
   pages:
     markup/templating: "Templating"
+    "https://twig.symfony.com/doc/2.x/": "Twig Docs@"
 
 Variables:
   icon: "icon-subscript"
@@ -37,21 +38,22 @@ Filters:
   itemClass: "code-item"
   pages:
     markup/filter-app: "| app"
-    markup/filter-page: "| page"
-    markup/filter-theme: "| theme"
-    markup/filter-media: "| media"
-    markup/filter-resize: "| resize"
+    markup/filter-asset: "| asset"
+    markup/filter-default: "| default"
     markup/filter-image-width: "| imageWidth"
     markup/filter-image-height: "| imageHeight"
-    markup/filter-md: "| md"
+    markup/filter-md: "| md[_line|_safe]"
+    markup/filter-media: "| media"
+    markup/filter-page: "| page"
     markup/filter-raw: "| raw"
-    markup/filter-default: "| default"
+    markup/filter-resize: "| resize"
+    markup/filter-theme: "| theme"
 
 Functions:
   icon: "icon-eraser"
   itemClass: "code-item"
   pages:
-    markup/function-str: "str()"
-    markup/function-form: "form()"
+    markup/function-str: "str_*()"
+    markup/function-form: "form_*()"
     markup/function-html: "html()"
     markup/function-dump: "dump()"

markup-filter-app.md

@@ -2,6 +2,8 @@
 
 The `| app` filter returns an address relative to the public path of the website. The result is an absolute URL, including the domain name and protocol, to the location specified in the filter parameter. The filter can be applied to any path.
 
+>**NOTE**: If an absolute URL is passed to this filter it will be returned unmodified. Only relative URLs are turned into absolute URLs relative to the web root.
+
 ```twig
 <link rel="icon" href="{{ '/favicon.ico' | app }}" />
 ```
@@ -12,6 +14,8 @@ If the website address is __https://example.com__ the above example would output
 <link rel="icon" href="https://example.com/favicon.ico" />
 ```
 
+>**NOTE**: When linking to static assets it is recommended to use the [`| asset`](filter-asset) filter instead.
+
 It can also be used for static URLs:
 
 ```twig

markup-filter-asset.md

@@ -0,0 +1,13 @@
+# | asset
+
+The asset filter (also available as a function, `asset()`) generates a URL for an asset using the current scheme of the request (HTTP or HTTPS):
+
+```twig
+{{ 'img/photo.jpg' | asset }}
+
+{# or #}
+
+{{ asset('img/photo.jpg') }}
+```
+
+See [Helpers#asset](../services/helpers#method-asset) for more information.

markup-filter-md.md

@@ -11,3 +11,27 @@ The above will output the following:
 ```html
 <p><strong>Text</strong> is bold.</p>
 ```
+
+# | md_line
+
+The `| md_line` filter converts the value from Markdown to HTML format, as inline element.
+
+    {{ '**Text** is bold.' | md_line }}
+
+The above will output the following:
+
+    <strong>Text</strong> is bold.
+
+# | md_safe
+
+The `| md_safe` filter converts the value from Markdown to HTML format, preventing `<code>` blocks caused by indentation.
+
+    {{ '    **Text** is bold.' | md_safe }}
+
+The above will output the following:
+
+    <p><strong>Text</strong> is bold.</p>
+
+instead of
+
+    <pre><code><strong>Text</strong> is bold.</p></code></pre>

markup-function-form.md

@@ -1,4 +1,4 @@
-# form()
+# form_*()
 
 Functions prefixed with `form_` perform tasks that are useful when dealing with forms. The helper maps directly to the `Form` PHP class and its methods. For example:
 

markup-function-str.md

@@ -1,4 +1,4 @@
-# str()
+# str_*()
 
 Functions prefixed with `str_` perform tasks that are useful when dealing with strings. The helper maps directly to the `Str` PHP class and its methods. For example:
 
@@ -14,73 +14,6 @@ is the PHP equivalent of the following:
 
 > **NOTE**: Methods in *camelCase* should be converted to *snake_case*.
 
-## str_limit()
+See [Helpers#helpers-string](../services/helpers#helpers-strings) for a list of all available `str_*` helpers.
 
-Limit the number of characters in a string.
-
-```twig
-{{ str_limit('The quick brown fox...', 100) }}
-```
-
-To add a suffix when limit is applied, pass it as the third argument. Defaults to `...`.
-
-```twig
-{{ str_limit('The quick brown fox...', 100, '... Read more!') }}
-```
-
-## str_words()
-
-Limit the number of words in a string.
-
-```twig
-{{ str_words('The quick brown fox...', 100) }}
-```
-
-To add a suffix when limit is applied, pass it as the third argument. Defaults to `...`.
-
-```twig
-{{ str_words('The quick brown fox...', 100, '... Read more!') }}
-```
-
-## str_camel()
-
-Convert a value to *camelCase*.
-
-```twig
-// Outputs: helloWorld
-{{ str_camel('hello world') }}
-```
-
-## str_studly()
-
-Convert a value to *StudlyCase*.
-
-```twig
-// Outputs: HelloWorld
-{{ str_studly('hello world') }}
-```
-
-## str_snake()
-
-Convert a value to *snake_case*.
-
-```twig
-// Outputs: hello_world
-{{ str_snake('hello world') }}
-```
-
-The second argument can supply a delimiter.
-
-```twig
-// Outputs: hello---world
-{{ str_snake('hello world', '---') }}
-```
-
-## str_plural()
-
-Get the plural form of an English word.
-
-```twig
-// Outputs: chickens
-{{ str_plural('chicken') }}
-```
+See [Laravel Helpers](https://laravel.com/docs/6.x/helpers#available-methods) for a list of all available `str_*` helpers that come from Laravel. Any helper that matches `Str::$camelCase` is available in Twig as `str_$snake_case` with the same parameters

services-helpers.md

@@ -16,6 +16,7 @@ Winter includes a variety of "helper" PHP functions. Many of these functions are
 ### Arrays
 
 <div class="collection-method-list" markdown="1">
+[Laravel `Arr::*()` Helpers](https://laravel.com/docs/6.x/helpers#available-methods)
 [array_add](#method-array-add)
 [array_divide](#method-array-divide)
 [array_dot](#method-array-dot)
@@ -56,6 +57,7 @@ Winter includes a variety of "helper" PHP functions. Many of these functions are
 ### Strings
 
 <div class="collection-method-list" markdown="1">
+[Laravel `Str::*()` Helpers](https://laravel.com/docs/6.x/helpers#available-methods)
 [camel_case](#method-camel-case)
 [class_basename](#method-class-basename)
 [e](#method-e)
@@ -773,6 +775,14 @@ Generate a URL for an asset using the current scheme of the request (HTTP or HTT
 $url = asset('img/photo.jpg');
 ```
 
+You can configure the asset URL host by setting the `ASSET_URL` variable in your `.env` file (or `asset_url` in your `config/app.php` file). This can be useful if you host your assets on an external service like Amazon S3 or another CDN:
+
+```php
+// ASSET_URL=http://example.com/assets
+
+$url = asset('img/photo.jpg'); // http://example.com/assets/img/photo.jpg
+```
+
 <a name="method-config"></a>
 #### `config()` {#collection-method}