added Link to variable scope page in the documentation for the assign tag

Fixes #878

CHANGELOG.md

@@ -8,6 +8,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - PHP8.3 support [#925](https://github.com/smarty-php/smarty/issues/925)
+- Backlink to GitHub in docs
+- Explain how to do escaping and set-up auto-escaping in docs [#865](https://github.com/smarty-php/smarty/issues/865)
+- Link to variable scope page in the documentation for the assign tag [#878](https://github.com/smarty-php/smarty/issues/878)
 
 ### Fixed
 - The {debug} tag was broken in v5 [#922](https://github.com/smarty-php/smarty/issues/922)

README.md

@@ -7,7 +7,7 @@ Smarty is a template engine for PHP, facilitating the separation of presentation
 Read the [documentation](https://smarty-php.github.io/smarty/) to find out how to use it. 
 
 ## Requirements
-Smarty v5 can be run with PHP 7.2 to PHP 8.2.
+Smarty v5 can be run with PHP 7.2 to PHP 8.3.
 
 ## Installation
 Smarty versions 3.1.11 or later can be installed with [Composer](https://getcomposer.org/).

docs/api/basics.md

@@ -89,4 +89,5 @@ Run this, and you will see:
 ```
 
 Note how the [escape modifier](../designers/language-modifiers/language-modifier-escape.md) 
-translated the `&` character into the proper HTML syntax `&`.
+translated the `&` character into the proper HTML syntax `&`.
+Read more about auto-escaping in the [next section](./configuring.md).

docs/api/configuring.md

@@ -122,6 +122,24 @@ $smarty->setCacheDir('/data/caches');
 $cacheDir = $smarty->getCacheDir();
 ```
 
+## Enabling auto-escaping
+By default, Smarty does not escape anything you render in your templates. If you use
+Smarty to render a HTML-page, this means that you will have to make sure that you do
+not render any characters that have a special meaning in HTML, such as `&`, `<` and `>`,
+or apply the [escape modifier](../designers/language-modifiers/language-modifier-escape.md) 
+to anything you want to render.
+
+If you forget to do so, you may break your HTML page, or even create a vulnerability for 
+attacks known as [XSS or Cross Site Scripting](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html).
+
+Luckily, you can tell Smarty to automatically apply the escape modifier to any dynamic part of your template.
+It's like Smarty magically adds `|escape` to every variable you use on a web page.
+
+Enable auto-escaping for HTML as follows:
+```php
+$smarty->setEscapeHtml(true);
+```
+
 ## Disabling compile check
 By default, Smarty tests to see if the
 current template has changed since the last time

docs/designers/language-builtin-functions/language-function-assign.md

@@ -8,12 +8,12 @@ execution of a template**.
 |----------------|------------|-----------------------------------------------------------------------|
 | var            |            | The name of the variable being assigned                               | 
 | value          |            | The value being assigned                                              |                             
-| scope          | (optional) | The scope of the assigned variable: \'parent\',\'root\' or \'global\' | 
+| scope          | (optional) | The scope of the assigned variable: 'parent','root' or 'global' | 
 
 ## Attributes of the {$var=...} syntax
 | Attribute Name | Required   | Description                                                           |
 |----------------|------------|-----------------------------------------------------------------------|
-| scope          | (optional) | The scope of the assigned variable: \'parent\',\'root\' or \'global\' | 
+| scope          | (optional) | The scope of the assigned variable: 'parent','root' or 'global' | 
 
 ## Option Flags
 | Name    | Description                                       |
@@ -102,6 +102,8 @@ A global variable is seen by all templates.
 {$foo="bar" scope="global"}
 ```
  
+For more information on variable scope, please read the page on [variable scopes](../language-variables/language-variable-scopes.md).
+
 To access `{assign}` variables from a php script use
 [`getTemplateVars()`](../../programmers/api-functions/api-get-template-vars.md). 
 Here's the template that creates the variable `$foo`.

docs/getting-started.md

@@ -1,7 +1,7 @@
 # Getting started
 
 ## Requirements
-Smarty can be run with PHP 7.2 to PHP 8.2.
+Smarty can be run with PHP 7.2 to PHP 8.3.
 
 ## Installation
 Smarty can be installed with [Composer](https://getcomposer.org/).
@@ -86,7 +86,7 @@ needs to be located in the [`$template_dir`](./programmers/api-variables/variabl
 
 ```smarty
 {* Smarty *}
-Hello {$name}, welcome to Smarty!
+<h1>Hello {$name|escape}, welcome to Smarty!</h1>
 ```
 
 > **Note**
@@ -132,6 +132,20 @@ Now, run your PHP file. You should see *"Hello Ned, welcome to Smarty!"*
 
 You have completed the basic setup for Smarty!
 
+## Escaping
+You may have noticed that the example template above renders the `$name` variable using
+the [escape modifier](./designers/language-modifiers/language-modifier-escape.md).  This 
+modifier makes string 'safe' to use in the context of an HTML page.
+
+If you are primarily using Smarty for HTML-pages, it is recommended to enable automatic
+escaping. This way, you don't have to add `|escape` to every variable you use on a web page. 
+Smarty will handle it automatically for you!
+
+Enable auto-escaping for HTML as follows:
+```php
+$smarty->setEscapeHtml(true);
+```
+
 ## Extended Setup
 
 This is a continuation of the [basic installation](#installation), please read that first!
@@ -156,6 +170,8 @@ class My_GuestBook extends Smarty {
         $this->setCompileDir('/web/www.example.com/guestbook/templates_c/');
         $this->setConfigDir('/web/www.example.com/guestbook/configs/');
         $this->setCacheDir('/web/www.example.com/guestbook/cache/');
+        
+        $this->setEscapeHtml(true);
 
         $this->caching = Smarty::CACHING_LIFETIME_CURRENT;
         $this->assign('app_name', 'Guest Book');

docs/index.md

@@ -26,6 +26,10 @@ and 480 for $height, the result is:
 - [Features](./features.md) - or "Why do I want Smarty?"
 
 ## Help
+- [Search or create an issue](https://github.com/smarty-php/smarty/issues)
 - [Upgrading from an older version](upgrading.md)
 - [Some random tips & tricks](./appendixes/tips.md)
 - [Troubleshooting](./appendixes/troubleshooting.md)
+
+## Source code
+- [Smarty repository at GitHub](https://github.com/smarty-php/smarty)