diff --git a/docs/api/basics.md b/docs/api/basics.md
new file mode 100644
index 00000000..0b58c028
--- /dev/null
+++ b/docs/api/basics.md
@@ -0,0 +1,92 @@
+# Basics
+
+## Installation
+For installation instructies, please see the [getting started section](../getting-started.md).
+
+## Rendering a template
+Here's how you create an instance of Smarty in your PHP scripts:
+```php
+<?php
+
+require 'vendor/autoload.php';
+use Smarty\Smarty;
+$smarty = new Smarty();
+```
+
+You now have a Smarty object that you can use to render templates.
+
+```php
+<?php
+
+require 'vendor/autoload.php';
+use Smarty\Smarty;
+$smarty = new Smarty();
+
+$smarty->display('string:The current smarty version is: {$smarty.version}.');
+// or 
+echo $smarty->fetch('string:The current smarty version is: {$smarty.version}.');
+```
+
+## Using file-based templates
+You probably want to manage your templates as files. Create a subdirectory called 'templates' and
+then configure Smarty to use that:
+
+```php
+<?php
+
+require 'vendor/autoload.php';
+use Smarty\Smarty;
+$smarty = new Smarty();
+
+$smarty->setTemplateDir(__DIR__ . '/templates');
+```
+
+Say you have a template file called 'version.tpl', stored in the 'templates' directory like this:
+```smarty
+<h1>Hi</h1>
+The current smarty version is: {$smarty.version|escape}.
+```
+
+You can now render this, using:
+```php
+<?php
+
+require 'vendor/autoload.php';
+use Smarty\Smarty;
+$smarty = new Smarty();
+
+$smarty->setTemplateDir(__DIR__ . '/templates');
+$smarty->display('version.tpl');
+```
+
+## Assigning variables
+
+Templates start to become really useful once you add variables to the mix.
+
+Create a template called 'footer.tpl' in the 'templates' directory like this:
+```smarty
+<small>Copyright {$companyName|escape}</small>
+```
+
+Now assign a value to the 'companyName' variable and render your template like this:
+
+```php
+<?php
+
+require 'vendor/autoload.php';
+use Smarty\Smarty;
+$smarty = new Smarty();
+
+$smarty->setTemplateDir(__DIR__ . '/templates');
+$smarty->assign('companyName', 'AC & ME Corp.');
+$smarty->display('footer.tpl');
+```
+
+Run this, and you will see:
+
+```html
+<small>Copyright AC &amp; ME Corp.</small>
+```
+
+Note how the [escape modifier](../designers/language-modifiers/language-modifier-escape.md) 
+translated the `&` character into the proper HTML syntax `&amp;`.
\ No newline at end of file
diff --git a/docs/api/caching/basics.md b/docs/api/caching/basics.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/caching/custom-storage-layers.md b/docs/api/caching/custom-storage-layers.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/caching/multiple-caches-per-pages.md b/docs/api/caching/multiple-caches-per-pages.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/configuring.md b/docs/api/configuring.md
new file mode 100644
index 00000000..b0f1ac65
--- /dev/null
+++ b/docs/api/configuring.md
@@ -0,0 +1,158 @@
+# Configuring Smarty
+
+## Setting the template path
+By default, Smarty looks for templates to render in `./templates`.
+
+You can change this, or even use multiple paths to use when looking for templates.
+
+If you need to change this, you can use `setTemplateDir()` or `addTemplateDir()`.
+Use `getTemplateDir()` to retrieve the configured paths.
+
+```php
+<?php
+
+ // set a single directory where the config files are stored
+$smarty->setTemplateDir('./config');
+
+// set multiple directories where config files are stored
+$smarty->setTemplateDir(['./config', './config_2', './config_3']);
+
+// add directory where config files are stored to the current list of dirs
+$smarty->addTemplateDir('./config_1');
+
+// add multiple directories to the current list of dirs
+$smarty->addTemplateDir([
+    './config_2',
+    './config_3',
+]);
+
+// chaining of method calls
+$smarty->setTemplateDir('./config')
+       ->addTemplateDir('./config_1')
+       ->addTemplateDir('./config_2');
+
+// get all directories where config files are stored
+$template_dirs = $smarty->getTemplateDir();
+var_dump($template_dirs); // array
+
+// get directory identified by key
+$template_dir = $smarty->getTemplateDir(0);
+var_dump($template_dir); // string
+```
+
+## Setting the path for compiled templates
+Smarty compiles templates to native PHP to be as fast as possible.
+The default path where these PHP-files are stored is `./templates_c`.
+
+If you need to change this, you can use `setCompileDir()`.
+Use `getCompileDir()` to retrieve the configured path.
+
+```php
+<?php
+
+// set another path to store compiled templates
+$smarty->setCompileDir('/data/compiled_templates');
+
+// get directory where compiled templates are stored
+$compileDir = $smarty->getCompileDir();
+```
+
+
+## Setting the config path
+Smarty can [load data from config files](./variables/config-files.md).
+By default, Smarty loads the config files from `./configs`.
+
+You can change this, or even use multiple paths to use when looking for config files.
+
+If you need to change this, you can use `setConfigDir()` or `addConfigDir()`.
+Use `getConfigDir()` to retrieve the configured paths.
+
+```php
+<?php
+
+ // set a single directory where the config files are stored
+$smarty->setConfigDir('./config');
+
+// set multiple directories where config files are stored
+$smarty->setConfigDir(['./config', './config_2', './config_3']);
+
+// add directory where config files are stored to the current list of dirs
+$smarty->addConfigDir('./config_1');
+
+// add multiple directories to the current list of dirs
+$smarty->addConfigDir([
+    './config_2',
+    './config_3',
+]);
+
+// chaining of method calls
+$smarty->setConfigDir('./config')
+       ->addConfigDir('./config_1', 'one')
+       ->addConfigDir('./config_2', 'two');
+
+// get all directories where config files are stored
+$config_dirs = $smarty->getConfigDir();
+var_dump($config_dirs); // array
+
+// get directory identified by key
+$config_dir = $smarty->getConfigDir(0);
+var_dump($config_dir); // string
+```
+
+## Setting the path for caches
+Even though Smarty runs templates as native PHP for maximum speed, it still needs to 
+execute the PHP code on each call. If your data doesn't change all that often, you
+may be able to speed up your application even more by using output caching.
+
+Output caching can be a tricky subject, so we devoted an entire [section to caching](./caching/basics.md).
+Be sure to read that if you want to use caching.
+
+By default, Smarty stores caches to PHP-files in a subdirectory named `./cache`.
+
+If you need to change this, you can use `setCacheDir()`.
+Use `getCacheDir()` to retrieve the configured path.
+
+```php
+<?php
+
+// set another path to store caches
+$smarty->setCacheDir('/data/caches');
+
+// get directory where cached templates are stored
+$cacheDir = $smarty->getCacheDir();
+```
+
+## Charset encoding
+
+There are a variety of encodings for textual data, ISO-8859-1 (Latin1)
+and UTF-8 being the most popular. Unless you change `\Smarty\Smarty::$_CHARSET`,
+Smarty recognizes `UTF-8` as the internal charset.
+
+> **Note**
+>
+> `ISO-8859-1` has been PHP\'s default internal charset since the
+> beginning. Unicode has been evolving since 1991. Since then, it has
+> become the one charset to conquer them all, as it is capable of
+> encoding most of the known characters even across different character
+> systems (latin, cyrillic, japanese, ...). `UTF-8` is unicode\'s most
+> used encoding, as it allows referencing the thousands of character
+> with the smallest size overhead possible.
+>
+> Since unicode and UTF-8 are very widespread nowadays, their use is
+> strongly encouraged.
+
+> **Note**
+>
+> Smarty\'s internals and core plugins are truly UTF-8 compatible since
+> Smarty 3.1.
+
+```php
+<?php
+    
+// use japanese character encoding
+mb_internal_charset('EUC-JP');
+
+\Smarty\Smarty::$_CHARSET = 'EUC-JP';
+$smarty = new \Smarty\Smarty();
+```
+     
diff --git a/docs/api/extending/block-tags.md b/docs/api/extending/block-tags.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/extending/extensions.md b/docs/api/extending/extensions.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/extending/introduction.md b/docs/api/extending/introduction.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/extending/modifiers.md b/docs/api/extending/modifiers.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/extending/tags.md b/docs/api/extending/tags.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/filters/output-filters.md b/docs/api/filters/output-filters.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/filters/postfilters.md b/docs/api/filters/postfilters.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/filters/prefilters.md b/docs/api/filters/prefilters.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/inheritance.md b/docs/api/inheritance.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/rendering.md b/docs/api/rendering.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/resources.md b/docs/api/resources.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/security.md b/docs/api/security.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/variables/assigning.md b/docs/api/variables/assigning.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/variables/config-files.md b/docs/api/variables/config-files.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/variables/objects.md b/docs/api/variables/objects.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/variables/static-class-methods.md b/docs/api/variables/static-class-methods.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/api/variables/streams.md b/docs/api/variables/streams.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/appendixes/tips.md b/docs/appendixes/tips.md
index 3c6e6b96..e4e38d4b 100644
--- a/docs/appendixes/tips.md
+++ b/docs/appendixes/tips.md
@@ -209,8 +209,7 @@ fetching the data up front?
 You can do this by writing a custom plugin for fetching the content and
 assigning it to a template variable.
 
-`function.load_ticker.php` - drop file in
-[`$plugins directory`](../programmers/api-variables/variable-plugins-dir.md)
+`function.load_ticker.php`
 
 ```php
 
diff --git a/docs/designers/language-modifiers/index.md b/docs/designers/language-modifiers/index.md
index 5e6bb51e..a384c95c 100644
--- a/docs/designers/language-modifiers/index.md
+++ b/docs/designers/language-modifiers/index.md
@@ -97,7 +97,7 @@ These parameters follow the modifier name and are separated by a `:`
     > `{(8+2)|count_characters}`.
 
 - Custom modifiers can be registered
-    with the [`registerPlugin()`](../programmers/api-functions/api-register-plugin.md)
+    with the [`registerPlugin()`](../../programmers/api-functions/api-register-plugin.md)
     function.
 
 See also [`registerPlugin()`](../../programmers/api-functions/api-register-plugin.md), [combining
diff --git a/docs/designers/language-modifiers/language-modifier-from-charset.md b/docs/designers/language-modifiers/language-modifier-from-charset.md
index bf4b4769..25c4d2d9 100644
--- a/docs/designers/language-modifiers/language-modifier-from-charset.md
+++ b/docs/designers/language-modifiers/language-modifier-from-charset.md
@@ -16,5 +16,5 @@ modifier](language-modifier-to-charset.md).
 > modifier should only be used in cases where the application cannot
 > anticipate that a certain string is required in another encoding.
 
-See also [Charset Encoding](../../programmers/charset.md), [to_charset
+See also [Configuring Smarty](../../api/configuring.md), [to_charset
 modifier](language-modifier-to-charset.md).
diff --git a/docs/designers/language-modifiers/language-modifier-to-charset.md b/docs/designers/language-modifiers/language-modifier-to-charset.md
index c0b00384..aa8cfd53 100644
--- a/docs/designers/language-modifiers/language-modifier-to-charset.md
+++ b/docs/designers/language-modifiers/language-modifier-to-charset.md
@@ -16,5 +16,5 @@ modifier](#language.modifier.from_charset).
 > modifier should only be used in cases where the application cannot
 > anticipate that a certain string is required in another encoding.
 
-See also [Charset Encoding](../../programmers/charset.md), [from_charset
+See also [Configuring Smarty](../../api/configuring.md), [from_charset
 modifier](language-modifier-from-charset.md).
diff --git a/docs/designers/language-variables/language-variables-smarty.md b/docs/designers/language-variables/language-variables-smarty.md
index da543fb6..b6dff73a 100644
--- a/docs/designers/language-variables/language-variables-smarty.md
+++ b/docs/designers/language-variables/language-variables-smarty.md
@@ -66,8 +66,7 @@ difference.
 
 ## {$smarty.const}
 
-You can access PHP constant values directly. See also [smarty
-constants](../../programmers/smarty-constants.md).
+You can access PHP constant values directly.
 
 ```php
 <?php
diff --git a/docs/images/favicon.ico b/docs/img/favicon.ico
similarity index 100%
rename from docs/images/favicon.ico
rename to docs/img/favicon.ico
diff --git a/docs/index.md b/docs/index.md
index 39b9f1a5..0604f2a8 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -20,30 +20,11 @@ and 480 for $height, the result is:
 </p>
 ```
 
-## Introduction
+## Getting Started
+- [Getting Started](./getting-started.md)
 - [Philosophy](./philosophy.md) - or "Why do I need a template engine?"
 - [Features](./features.md) - or "Why do I want Smarty?"
-- [Getting Started](./getting-started.md)
 
-## Smarty for template designers
-- [Basic Syntax](designers/language-basic-syntax/index.md)
-- [Variables](designers/language-variables/index.md)
-- [Variable Modifiers](designers/language-modifiers/index.md)
-- [Combining Modifiers](./designers/language-combining-modifiers.md)
-- [Built-in Functions](designers/language-builtin-functions/index.md)
-- [Custom Functions](designers/language-custom-functions/index.md)
-- [Config Files](./designers/config-files.md)
-- [Debugging Console](./designers/chapter-debugging-console.md)
-
-## Smarty for php developers
-- [Charset Encoding](./programmers/charset.md)
-- [Smarty Class Variables](./programmers/api-variables.md)
-- [Smarty Class Methods](./programmers/api-functions.md)
-- [Caching](./programmers/caching.md)
-- [Resources](./programmers/resources.md)
-- [Advanced Features](./programmers/advanced-features.md)
-- [Extending Smarty With Plugins](./programmers/plugins.md)
-
-## Other
+## Help
 - [Some random tips & tricks](./appendixes/tips.md)
 - [Troubleshooting](./appendixes/troubleshooting.md)
diff --git a/docs/programmers/advanced-features.md b/docs/programmers/advanced-features.md
deleted file mode 100644
index 60d4416b..00000000
--- a/docs/programmers/advanced-features.md
+++ /dev/null
@@ -1,14 +0,0 @@
-Advanced Features {#advanced.features}
-=================
-
-## Table of contents
-
-- [Security](./advanced-features/advanced-features-security.md)
-- [Changing settings by template](./advanced-features/advanced-features-template-settings.md)
-- [Template Inheritance](./advanced-features/advanced-features-template-inheritance.md)
-- [Streams](./advanced-features/advanced-features-streams.md)
-- [Objects](./advanced-features/advanced-features-objects.md)
-- [Static Classes](./advanced-features/advanced-features-static-classes.md)
-- [Prefilters](./advanced-features/advanced-features-prefilters.md)
-- [Postfilters](./advanced-features/advanced-features-postfilters.md)
-- [Output Filters](./advanced-features/advanced-features-outputfilters.md)
diff --git a/docs/programmers/advanced-features/advanced-features-objects.md b/docs/programmers/advanced-features/advanced-features-objects.md
index b681945e..65b202c1 100644
--- a/docs/programmers/advanced-features/advanced-features-objects.md
+++ b/docs/programmers/advanced-features/advanced-features-objects.md
@@ -1,5 +1,4 @@
-Objects {#advanced.features.objects}
-=======
+# Objects
 
 Smarty allows access to PHP [objects](https://www.php.net/object) through
 the templates.
@@ -14,11 +13,11 @@ the templates.
 
 There are two ways to access them.
 
--   One way is to [register objects](#api.register.object) to the
+-   One way is to [register objects](../api-functions/api-register-object.md) to the
     template, then use access them via syntax similar to [custom
-    functions](#language.custom.functions).
+    functions](../../designers/language-custom-functions/index.md).
 
--   The other way is to [`assign()`](#api.assign) objects to the
+-   The other way is to [`assign()`](../api-functions/api-assign.md) objects to the
     templates and access them much like any other assigned variable.
 
 The first method has a much nicer template syntax. It is also more
@@ -29,14 +28,14 @@ determined by your needs, but use the first method whenever possible to
 keep template syntax to a minimum.
 
 If security is enabled, no private methods or functions can be accessed
-(beginning with \'\_\'). If a method and property of the same name exist,
+(beginning with '_'). If a method and property of the same name exist,
 the method will be used.
 
 You can restrict the methods and properties that can be accessed by
 listing them in an array as the third registration parameter.
 
 By default, parameters passed to objects through the templates are
-passed the same way [custom functions](#language.custom.functions) get
+passed the same way [custom functions](../../designers/language-custom-functions/index.md) get
 them. An associative array is passed as the first parameter, and the
 smarty object as the second. If you want the parameters passed one at a
 time for each argument like traditional object parameter passing, set
@@ -47,53 +46,50 @@ and contains a list of methods that should be treated as blocks. That
 means these methods have a closing tag in the template
 (`{foobar->meth2}...{/foobar->meth2}`) and the parameters to the methods
 have the same synopsis as the parameters for
-[`block-function-plugins`](#plugins.block.functions): They get the four
+[`block-function-plugins`](../plugins/plugins-block-functions.md): They get the four
 parameters `$params`, `$content`, `$smarty` and `&$repeat` and they also
 behave like block-function-plugins.
 
+```php
+<?php
+// the object
 
-    <?php
-    // the object
-
-    class My_Object {
-        function meth1($params, $smarty_obj) {
-            return 'this is my meth1';
-        }
+class My_Object {
+    function meth1($params, $smarty_obj) {
+        return 'this is my meth1';
     }
+}
 
-    $myobj = new My_Object;
+$myobj = new My_Object;
 
-    // registering the object (will be by reference)
-    $smarty->registerObject('foobar',$myobj);
+// registering the object (will be by reference)
+$smarty->registerObject('foobar',$myobj);
 
-    // if we want to restrict access to certain methods or properties, list them
-    $smarty->registerObject('foobar',$myobj,array('meth1','meth2','prop1'));
+// if we want to restrict access to certain methods or properties, list them
+$smarty->registerObject('foobar',$myobj,array('meth1','meth2','prop1'));
 
-    // if you want to use the traditional object parameter format, pass a boolean of false
-    $smarty->registerObject('foobar',$myobj,null,false);
+// if you want to use the traditional object parameter format, pass a boolean of false
+$smarty->registerObject('foobar',$myobj,null,false);
 
-    // We can also assign objects. assign_by_ref when possible.
-    $smarty->assign_by_ref('myobj', $myobj);
+// We can also assign objects. assign_by_ref when possible.
+$smarty->assign_by_ref('myobj', $myobj);
 
-    $smarty->display('index.tpl');
-    ?>
+$smarty->display('index.tpl');
+```
 
+And here's how to access your objects in `index.tpl`:
+
+```smarty
+{* access our registered object *}
+{foobar->meth1 p1='foo' p2=$bar}
+
+{* you can also assign the output *}
+{foobar->meth1 p1='foo' p2=$bar assign='output'}
+the output was {$output}
+
+{* access our assigned object *}
+{$myobj->meth1('foo',$bar)}
+```
       
-
-And here\'s how to access your objects in `index.tpl`:
-
-
-    {* access our registered object *}
-    {foobar->meth1 p1='foo' p2=$bar}
-
-    {* you can also assign the output *}
-    {foobar->meth1 p1='foo' p2=$bar assign='output'}
-    the output was {$output}
-
-    {* access our assigned object *}
-    {$myobj->meth1('foo',$bar)}
-
-      
-
-See also [`registerObject()`](#api.register.object) and
-[`assign()`](#api.assign).
+See also [`registerObject()`](../api-functions/api-register-object.md) and
+[`assign()`](../api-functions/api-assign.md).
diff --git a/docs/programmers/advanced-features/advanced-features-outputfilters.md b/docs/programmers/advanced-features/advanced-features-outputfilters.md
index a4756366..5aee0be0 100644
--- a/docs/programmers/advanced-features/advanced-features-outputfilters.md
+++ b/docs/programmers/advanced-features/advanced-features-outputfilters.md
@@ -1,41 +1,37 @@
-Output Filters {#advanced.features.outputfilters}
-==============
+# Output Filters
 
-When the template is invoked via [`display()`](#api.display) or
-[`fetch()`](#api.fetch), its output can be sent through one or more
+When the template is invoked via [`display()`](../api-functions/api-display.md) or
+[`fetch()`](../api-functions/api-fetch.md), its output can be sent through one or more
 output filters. This differs from
-[`postfilters`](#advanced.features.postfilters) because postfilters
+[`postfilters`](advanced-features-postfilters.md) because postfilters
 operate on compiled templates before they are saved to the disk, whereas
 output filters operate on the template output when it is executed.
 
-Output filters can be either [registered](#api.register.filter) or
-loaded from the [plugins directory](#variable.plugins.dir) by using the
-[`loadFilter()`](#api.load.filter) method. Smarty will
+Output filters can be either [registered](../api-functions/api-register-filter.md) 
+or added as part of a [custom extension](extending-smarty.md). Smarty will
 pass the template output as the first argument, and expect the function
 to return the result of the processing.
 
+```php
+<?php
+// put this in your application
+function protect_email($tpl_output, \Smarty\Template\ $template)
+{
+    $tpl_output =
+       preg_replace('!(\S+)@([a-zA-Z0-9\.\-]+\.([a-zA-Z]{2,3}|[0-9]{1,3}))!',
+                    '$1%40$2', $tpl_output);
+    return $tpl_output;
+}
 
-    <?php
-    // put this in your application
-    function protect_email($tpl_output, \Smarty\Template\ $template)
-    {
-        $tpl_output =
-           preg_replace('!(\S+)@([a-zA-Z0-9\.\-]+\.([a-zA-Z]{2,3}|[0-9]{1,3}))!',
-                        '$1%40$2', $tpl_output);
-        return $tpl_output;
-    }
-
-    // register the outputfilter
-    $smarty->registerFilter("output","protect_email");
-    $smarty->display("index.tpl');
-
-    // now any occurrence of an email address in the template output will have
-    // a simple protection against spambots
-    ?>
+// register the outputfilter
+$smarty->registerFilter("output","protect_email");
+$smarty->display("index.tpl');
 
+// now any occurrence of an email address in the template output will have
+// a simple protection against spambots
+```
         
 
-See also [`registerFilter()`](#api.register.filter),
-[`loadFilter()`](#api.load.filter),
-[postfilters](#advanced.features.postfilters) and
-[`$plugins_dir`](#variable.plugins.dir).
+See also [`registerFilter()`](../api-functions/api-register-filter.md),
+[`addExtension()`](../api-functions/add-extension.md) and
+[postfilters](#advanced.features.postfilters).
diff --git a/docs/programmers/advanced-features/advanced-features-postfilters.md b/docs/programmers/advanced-features/advanced-features-postfilters.md
index e516f8a7..5fbf4693 100644
--- a/docs/programmers/advanced-features/advanced-features-postfilters.md
+++ b/docs/programmers/advanced-features/advanced-features-postfilters.md
@@ -1,39 +1,35 @@
-Postfilters {#advanced.features.postfilters}
-===========
+# Postfilters
 
 Template postfilters are PHP functions that your templates are ran
-through *after they are compiled*. Postfilters can be either
-[registered](#api.register.filter) or loaded from the [plugins
-directory](#variable.plugins.dir) by using the
-[`loadFilter()`](#api.load.filter) function. Smarty will
+through *after they are compiled*. 
+
+Postfilters can be
+[registered](../api-functions/api-register-filter.md) or added as part of a [custom extension](extending-smarty.md). Smarty will
 pass the compiled template code as the first argument, and expect the
 function to return the result of the processing.
 
+```php
+<?php
+// put this in your application
+function add_header_comment($tpl_source, \Smarty\Template\ $template)
+{
+    return "<?php echo \"<!-- Created by Smarty! -->\n\"; ?>\n".$tpl_source;
+}
 
-    <?php
-    // put this in your application
-    function add_header_comment($tpl_source, \Smarty\Template\ $template)
-    {
-        return "<?php echo \"<!-- Created by Smarty! -->\n\"; ?>\n".$tpl_source;
-    }
-
-    // register the postfilter
-    $smarty->registerFilter('post','add_header_comment');
-    $smarty->display('index.tpl');
-    ?>
-
-      
+// register the postfilter
+$smarty->registerFilter('post','add_header_comment');
+$smarty->display('index.tpl');
+```
 
 The postfilter above will make the compiled Smarty template `index.tpl`
 look like:
 
+```smarty
+<!-- Created by Smarty! -->
+{* rest of template content... *}
+```
 
-    <!-- Created by Smarty! -->
-    {* rest of template content... *}
-
-      
-
-See also [`registerFilter()`](#api.register.filter),
-[prefilters](#advanced.features.prefilters),
-[outputfilters](#advanced.features.outputfilters), and
-[`loadFilter()`](#api.load.filter).
+See also [`registerFilter()`](../api-functions/api-register-filter.md),
+[prefilters](advanced-features-prefilters.md),
+[outputfilters](advanced-features-outputfilters.md), and
+[`addExtension()`](../api-functions/add-extension.md).
diff --git a/docs/programmers/advanced-features/advanced-features-prefilters.md b/docs/programmers/advanced-features/advanced-features-prefilters.md
index a71d0532..6b50fd33 100644
--- a/docs/programmers/advanced-features/advanced-features-prefilters.md
+++ b/docs/programmers/advanced-features/advanced-features-prefilters.md
@@ -1,35 +1,31 @@
-Prefilters {#advanced.features.prefilters}
-==========
+# Prefilters
 
 Template prefilters are PHP functions that your templates are ran
 through *before they are compiled*. This is good for preprocessing your
 templates to remove unwanted comments, keeping an eye on what people are
 putting in their templates, etc.
 
-Prefilters can be either [registered](#api.register.filter) or loaded
-from the [plugins directory](#variable.plugins.dir) by using
-[`loadFilter()`](#api.load.filter) function.
+Prefilters can be
+[registered](../api-functions/api-register-filter.md) or added as part of a [custom extension](extending-smarty.md).
 
 Smarty will pass the template source code as the first argument, and
 expect the function to return the resulting template source code.
 
 This will remove all the html comments in the template source.
 
+```php
+<?php
+// put this in your application
+function remove_dw_comments($tpl_source, \Smarty\Template\ $template)
+{
+    return preg_replace("/<!--#.*-->/U",'',$tpl_source);
+}
 
-    <?php
-    // put this in your application
-    function remove_dw_comments($tpl_source, \Smarty\Template\ $template)
-    {
-        return preg_replace("/<!--#.*-->/U",'',$tpl_source);
-    }
+// register the prefilter
+$smarty->registerFilter('pre','remove_dw_comments');
+$smarty->display('index.tpl');
+```
 
-    // register the prefilter
-    $smarty->registerFilter('pre','remove_dw_comments');
-    $smarty->display('index.tpl');
-    ?>
-
-      
-
-See also [`registerFilter()`](#api.register.filter),
-[postfilters](#advanced.features.postfilters) and
-[`loadFilter()`](#api.load.filter).
+See also [`registerFilter()`](../api-functions/api-register-filter.md),
+[postfilters](advanced-features-postfilters.md), and
+[`addExtension()`](../api-functions/add-extension.md).
diff --git a/docs/programmers/advanced-features/advanced-features-security.md b/docs/programmers/advanced-features/advanced-features-security.md
index 4379eaad..c3dea45b 100644
--- a/docs/programmers/advanced-features/advanced-features-security.md
+++ b/docs/programmers/advanced-features/advanced-features-security.md
@@ -1,21 +1,20 @@
-Security {#advanced.features.security}
-========
+# Security
 
 Security is good for situations when you have untrusted parties editing
 the templates e.g. via ftp, and you want to reduce the risk of system
 security compromises through the template language.
 
 The settings of the security policy are defined by properties of an
-instance of the Smarty\_Security class. These are the possible settings:
+instance of the \Smarty\Security class. These are the possible settings:
 
 -   `$secure_dir` is an array of template directories that are
-    considered secure. [`$template_dir`](#variable.template.dir)
+    considered secure. A [template dir](../../api/configuring.md#setting-the-template-path--s-) is
     considered secure implicitly. The default is an empty array.
    
 - `$trusted_uri` is an array of regular expressions matching URIs that
     are considered trusted. This security directive used by
-    [`{fetch}`](#language.function.fetch) and
-    [`{html_image}`](#language.function.html.image). URIs passed to
+    [`{fetch}`](../../designers/language-custom-functions/language-function-fetch.md) and
+    [`{html_image}`](../../designers/language-custom-functions/language-function-html-image.md). URIs passed to
     these functions are reduced to `{$PROTOCOL}://{$HOSTNAME}` to allow
     simple regular expressions (without having to deal with edge cases
     like authentication-tokens).
@@ -24,33 +23,27 @@ instance of the Smarty\_Security class. These are the possible settings:
     the following URIs:
 
     -   `http://smarty.net/foo`
-
     -   `http://smarty.net/foo`
-
     -   `http://www.smarty.net/foo`
-
     -   `http://smarty.net/foo`
-
     -   `https://foo.bar.www.smarty.net/foo/bla?blubb=1`
 
     but deny access to these URIs:
 
     -   `http://smarty.com/foo` (not matching top-level domain \"com\")
-
     -   `ftp://www.smarty.net/foo` (not matching protocol \"ftp\")
-
     -   `http://www.smarty.net.otherdomain.com/foo` (not matching end of
         domain \"smarty.net\")
 
 -   `$static_classes` is an array of classes that are considered
     trusted. The default is an empty array which allows access to all
     static classes. To disable access to all static classes set
-    \$static\_classes = null.
+    $static_classes = null.
 
 -   `$streams` is an array of streams that are considered trusted and
     can be used from within template. To disable access to all streams
-    set \$streams = null. An empty array ( \$streams = array() ) will
-    allow all streams. The default is array(\'file\').
+    set $streams = null. An empty array ( $streams = [] ) will
+    allow all streams. The default is array('file').
 
 -   `$allowed_modifiers` is an array of (registered / autoloaded)
     modifiers that should be accessible to the template. If this array
@@ -69,49 +62,49 @@ instance of the Smarty\_Security class. These are the possible settings:
     block and filter plugins that may not be accessible to the template.
 
 -   `$allow_constants` is a boolean flag which controls if constants can
-    be accessed by the template. The default is \"true\".
+    be accessed by the template. The default is "true".
 
 -   `$allow_super_globals` is a boolean flag which controls if the PHP
     super globals can be accessed by the template. The default is
-    \"true\".
+    "true".
 
 If security is enabled, no private methods, functions or properties of
 static classes or assigned objects can be accessed (beginning with
-\'\_\') by the template.
+'_') by the template.
 
 To customize the security policy settings you can extend the
-Smarty\_Security class or create an instance of it.
+\Smarty\Security class or create an instance of it.
 
+```php
+<?php
 
-    <?php
+use Smarty\Smarty;
 
-    use Smarty\Smarty;
+class My_Security_Policy extends \Smarty\Security {
+  public $allow_constants = false;
+}
+$smarty = new Smarty();
+// enable security
+$smarty->enableSecurity('My_Security_Policy');
+```
 
-    class My_Security_Policy extends \Smarty\Security {
-      public $allow_constants = false;
-    }
-    $smarty = new Smarty();
-    // enable security
-    $smarty->enableSecurity('My_Security_Policy');
-    ?>
+```php
+<?php
+use Smarty\Smarty;
+$smarty = new Smarty();
+$my_security_policy = new \Smarty\Security($smarty);
+$my_security_policy->allow_constants = false;
+// enable security
+$smarty->enableSecurity($my_security_policy);
+```
 
-
-    <?php
-    use Smarty\Smarty;
-    $smarty = new Smarty();
-    $my_security_policy = new \Smarty\Security($smarty);
-    $my_security_policy->allow_constants = false;
-    // enable security
-    $smarty->enableSecurity($my_security_policy);
-    ?>
-
-
-    <?php
-    use Smarty\Smarty;
-    $smarty = new Smarty();
-    // enable default security
-    $smarty->enableSecurity();
-    ?>
+```php
+<?php
+use Smarty\Smarty;
+$smarty = new Smarty();
+// enable default security
+$smarty->enableSecurity();
+```
 
 > **Note**
 >
diff --git a/docs/programmers/advanced-features/advanced-features-static-classes.md b/docs/programmers/advanced-features/advanced-features-static-classes.md
index 8ef79113..52e58549 100644
--- a/docs/programmers/advanced-features/advanced-features-static-classes.md
+++ b/docs/programmers/advanced-features/advanced-features-static-classes.md
@@ -1,7 +1,6 @@
-Static Classes {#advanced.features.static.classes}
-==============
+# Static Classes
 
-You can directly access static classes. The syntax is the same as in
+You can directly access static classes. The syntax is roughly the same as in
 PHP.
 
 > **Note**
@@ -12,16 +11,29 @@ PHP.
 > plugins which insulate templates from PHP classes/objects. Use at your
 > own discretion. See the Best Practices section of the Smarty website.
 
+## Examples
 
-    {assign var=foo value=myclass::BAR}  <--- class constant BAR
+**class constant BAR** 
+```smarty
+{assign var=foo value=myclass::BAR}
+```
 
-    {assign var=foo value=myclass::method()}  <--- method result
+**method result**
+```smarty
+{assign var=foo value=myclass::method()} 
+```
 
-    {assign var=foo value=myclass::method1()->method2}  <--- method chaining
+**method chaining**
+```smarty
+{assign var=foo value=myclass::method1()->method2}
+```
 
-    {assign var=foo value=myclass::$bar}  <--- property bar of class myclass
+**property bar of class myclass**
+```smarty
+{assign var=foo value=myclass::$bar} 
+```
 
-    {assign var=foo value=$bar::method}  <--- using Smarty variable bar as class name
-
-
-      
+**using Smarty variable bar as class name**
+```smarty
+{assign var=foo value=$bar::method}
+```
diff --git a/docs/programmers/advanced-features/advanced-features-streams.md b/docs/programmers/advanced-features/advanced-features-streams.md
index d6f7a0de..93d5c15e 100644
--- a/docs/programmers/advanced-features/advanced-features-streams.md
+++ b/docs/programmers/advanced-features/advanced-features-streams.md
@@ -1,15 +1,13 @@
-Streams {#advanced.features.streams}
-=======
+# Streams
 
-You can also use streams to call variables. *{\$foo:bar}* will use the
+You can also use streams to call variables. *{$foo:bar}* will use the
 *foo://bar* stream to get the template variable.
 
 Using a PHP stream for a template variable resource from within a
 template.
 
+```smarty
+{$foo:bar}
+```
 
-    {$foo:bar}
-
-      
-
-See also [`Template Resources`](#resources)
+See also [`Template Resources`](../resources.md)
diff --git a/docs/programmers/advanced-features/advanced-features-template-inheritance.md b/docs/programmers/advanced-features/advanced-features-template-inheritance.md
index ce47310c..8fd5fd63 100644
--- a/docs/programmers/advanced-features/advanced-features-template-inheritance.md
+++ b/docs/programmers/advanced-features/advanced-features-template-inheritance.md
@@ -1,5 +1,4 @@
-Template Inheritance {#advanced.features.template.inheritance}
-====================
+# Template Inheritance
 
 Inheritance brings the concept of Object Oriented Programming to
 templates, allowing you to define one (or more) base templates that can
@@ -10,26 +9,26 @@ can override all or some of the parent named block areas.
     extend a file that extends another one that extends another one and
     so on.
 
--   The child templates can not define any content besides what\'s
-    inside [`{block}`](#language.function.block) tags they override.
-    Anything outside of [`{block}`](#language.function.block) tags will
+-   The child templates can not define any content besides what's
+    inside [`{block}`](../../designers/language-builtin-functions/language-function-block.md) tags they override.
+    Anything outside of [`{block}`](../../designers/language-builtin-functions/language-function-block.md) tags will
     be removed.
 
--   The content of [`{block}`](#language.function.block) tags from child
+-   The content of [`{block}`](../../designers/language-builtin-functions/language-function-block.md) tags from child
     and parent templates can be merged by the `append` or `prepend`
-    [`{block}`](#language.function.block) tag option flags and
+    [`{block}`](../../designers/language-builtin-functions/language-function-block.md) tag option flags and
     `{$smarty.block.parent}` or `{$smarty.block.child}` placeholders.
 
 -   Template inheritance is a compile time process which creates a
     single compiled template file. Compared to corresponding solutions
     based on subtemplates included with the
-    [`{include}`](#language.function.include) tag it does have much
+    [`{include}`](../../designers/language-builtin-functions/language-function-include.md) tag it does have much
     better performance when rendering.
 
 -   The child template extends its parent defined with the
-    [`{extends}`](#language.function.extends) tag, which must be the
+    [`{extends}`](../../designers/language-builtin-functions/language-function-extends.md) tag, which must be the
     first line in the child template. Instead of using the
-    [`{extends}`](#language.function.extends) tags in the template files
+    [`{extends}`](../../designers/language-builtin-functions/language-function-extends.md) tags in the template files
     you can define the whole template inheritance tree in the PHP script
     when you are calling [`fetch()`](#api.fetch) or
     [`display()`](#api.display) with the `extends:` template resource
@@ -44,85 +43,86 @@ can override all or some of the parent named block areas.
 > **Note**
 >
 > If you have a subtemplate which is included with
-> [`{include}`](#language.function.include) and it contains
-> [`{block}`](#language.function.block) areas it works only if the
-> [`{include}`](#language.function.include) itself is called from within
-> a surrounding [`{block}`](#language.function.block). In the final
+> [`{include}`](../../designers/language-builtin-functions/language-function-include.md) and it contains
+> [`{block}`](../../designers/language-builtin-functions/language-function-block.md) areas it works only if the
+> [`{include}`](../../designers/language-builtin-functions/language-function-include.md) itself is called from within
+> a surrounding [`{block}`](../../designers/language-builtin-functions/language-function-block.md). In the final
 > parent template you may need a dummy
-> [`{block}`](#language.function.block) for it.
+> [`{block}`](../../designers/language-builtin-functions/language-function-block.md) for it.
 
 layout.tpl (parent)
 
-
-    <html>
+```smarty
+<html>
     <head>
       <title>{block name=title}Default Page Title{/block}</title>
       {block name=head}{/block}
     </head>
     <body>
-    {block name=body}{/block}
+        {block name=body}{/block}
     </body>
-    </html>
-
+</html>
+```
       
 
 myproject.tpl (child)
 
-
-    {extends file='layout.tpl'}
-    {block name=head}
-      <link href="/css/mypage.css" rel="stylesheet" type="text/css"/>
-      <script src="/js/mypage.js"></script>
-    {/block}
-
+```smarty
+{extends file='layout.tpl'}
+{block name=head}
+  <link href="/css/mypage.css" rel="stylesheet" type="text/css"/>
+  <script src="/js/mypage.js"></script>
+{/block}
+```
 
       
 
 mypage.tpl (grandchild)
 
-
-    {extends file='myproject.tpl'}
-    {block name=title}My Page Title{/block}
-    {block name=head}
-      <link href="/css/mypage.css" rel="stylesheet" type="text/css"/>
-      <script src="/js/mypage.js"></script>
-    {/block}
-    {block name=body}My HTML Page Body goes here{/block}
-
+```smarty
+{extends file='myproject.tpl'}
+{block name=title}My Page Title{/block}
+{block name=head}
+  <link href="/css/mypage.css" rel="stylesheet" type="text/css"/>
+  <script src="/js/mypage.js"></script>
+{/block}
+{block name=body}My HTML Page Body goes here{/block}
+```
       
 
 To render the above use
 
-
-     $smarty->display('mypage.tpl');
+```php
+<?php
+$smarty->display('mypage.tpl');
+```
 
 The resulting output is
 
-
-    <html>
+```smarty
+<html>
     <head>
       <title>My Page Title</title>
       <link href="/css/mypage.css" rel="stylesheet" type="text/css"/>
       <script src="/js/mypage.js"></script>
     </head>
     <body>
-    My HTML Page Body goes here
+     My HTML Page Body goes here
     </body>
-    </html>
+</html>
+```
 
-Instead of using [`{extends}`](#language.function.extends) tags in the
+Instead of using [`{extends}`](../../designers/language-builtin-functions/language-function-extends.md) tags in the
 template files you can define the inheritance tree in your PHP script by
-using the [`extends:` resource](#resources.extends) type.
+using the [`extends:` resource](../resources/resources-extends.md) type.
 
 The code below will return same result as the example above.
 
+```php
+<?php
+$smarty->display('extends:layout.tpl|myproject.tpl|mypage.tpl'); 
+```
 
-    <?php
-    $smarty->display('extends:layout.tpl|myproject.tpl|mypage.tpl'); 
-    ?>
-
-       
-
-See also [`{block}`](#language.function.block),
-[`{extends}`](#language.function.extends) and [`extends:`
-resource](#resources.extends)
+See also [`{block}`](../../designers/language-builtin-functions/language-function-block.md),
+[`{extends}`](../../designers/language-builtin-functions/language-function-extends.md) and [`extends:`
+resource](../resources/resources-extends.md)
diff --git a/docs/programmers/advanced-features/advanced-features-template-settings.md b/docs/programmers/advanced-features/advanced-features-template-settings.md
deleted file mode 100644
index b06430ff..00000000
--- a/docs/programmers/advanced-features/advanced-features-template-settings.md
+++ /dev/null
@@ -1,32 +0,0 @@
-Changing settings by template {#advanced.features.template.settings}
-=============================
-
-Normally you configure the Smarty settings by modifying the
-[`Smarty class variables`](#api.variables). Furthermore you can register
-plugins, filters etc. with [`Smarty functions`](#api.functions).
-Modifications done to the Smarty object will be global for all
-templates.
-
-However the Smarty class variables and functions can be accessed or
-called by individual template objects. Modification done to a template
-object will apply only for that template and its included subtemplates.
-
-
-    <?php
-    $tpl = $smarty->createTemplate('index.tpl);
-    $tpl->cache_lifetime = 600;
-    //or
-    $tpl->setCacheLifetime(600);
-    $smarty->display($tpl);
-    ?>
-
-        
-
-
-    <?php
-    $tpl = $smarty->createTemplate('index.tpl);
-    $tpl->registerPlugin('modifier','mymodifier');
-    $smarty->display($tpl);
-    ?>
-
-        
diff --git a/docs/programmers/advanced-features/extending-smarty.md b/docs/programmers/advanced-features/extending-smarty.md
new file mode 100644
index 00000000..c0a90a65
--- /dev/null
+++ b/docs/programmers/advanced-features/extending-smarty.md
@@ -0,0 +1,3 @@
+# Extending Smarty
+
+@TODO
diff --git a/docs/programmers/api-functions.md b/docs/programmers/api-functions.md
deleted file mode 100644
index e2ea1f51..00000000
--- a/docs/programmers/api-functions.md
+++ /dev/null
@@ -1,62 +0,0 @@
-Smarty Class Methods {#api.functions}
-====================
-
-## Table of contents
-
-- [addConfigDir()](./api-functions/api-add-config-dir.md) — add a directory to the list of directories where config files are stored
-- [addPluginsDir()](./api-functions/api-add-plugins-dir.md) — add a directory to the list of directories where plugins are stored
-- [addTemplateDir()](./api-functions/api-add-template-dir.md) — add a directory to the list of directories where templates are stored
-- [append()](./api-functions/api-append.md) — append an element to an assigned array
-- [appendByRef()](./api-functions/api-append-by-ref.md) — append values  by reference
-- [assign()](./api-functions/api-assign.md) — assign variables/objects to the templates
-- [assignByRef()](./api-functions/api-assign-by-ref.md) — assign values by reference
-- [clearAllAssign()](./api-functions/api-clear-all-assign.md) — clears the values of all assigned variables
-- [clearAllCache()](./api-functions/api-clear-all-cache.md) — clears the entire template cache
-- [clearAssign()](./api-functions/api-clear-assign.md) — clears the value of an assigned variable
-- [clearCache()](./api-functions/api-clear-cache.md) — clears the cache for a specific template
-- [clearCompiledTemplate()](./api-functions/api-clear-compiled-tpl.md) — clears the compiled version of the specified template resource
-- [clearConfig()](./api-functions/api-clear-config.md) — clears assigned config variables
-- [compileAllConfig()](./api-functions/api-compile-all-config.md) — compiles all known config files
-- [compileAllTemplates()](./api-functions/api-compile-all-templates.md) — compiles all known templates
-- [configLoad()](./api-functions/api-config-load.md) —  loads config file  data and assigns it to the template
-- [createData()](./api-functions/api-create-data.md) — creates a data object
-- [createTemplate()](./api-functions/api-create-template.md) — returns a template object
-- [disableSecurity()](./api-functions/api-disable-security.md) — disables template security
-- [display()](./api-functions/api-display.md) — displays the template
-- [enableSecurity()](./api-functions/api-enable-security.md) — enables template security
-- [fetch()](./api-functions/api-fetch.md) — returns the template output
-- [getCacheDir()](./api-functions/api-get-cache-dir.md) — return the directory where the rendered template's output is stored
-- [getCompileDir()](./api-functions/api-get-compile-dir.md) — returns the directory where compiled templates are stored
-- [getConfigDir()](./api-functions/api-get-config-dir.md) — return the directory where config files are stored
-- [getConfigVars()](./api-functions/api-get-config-vars.md) — returns the given loaded config variable value
-- [getPluginsDir()](./api-functions/api-get-plugins-dir.md) — return the directory where plugins are stored
-- [getRegisteredObject()](./api-functions/api-get-registered-object.md) — returns a reference to a registered object
-- [getTemplateDir()](./api-functions/api-get-template-dir.md) — return the directory where templates are stored
-- [getTemplateVars()](./api-functions/api-get-template-vars.md) — returns  assigned variable value(s)
-- [isCached()](./api-functions/api-is-cached.md) — returns true if there is a valid cache for this template
-- [loadFilter()](./api-functions/api-load-filter.md) — load a filter plugin
-- [muteExpectedErrors()](./api-functions/api-mute-expected-errors.md) — mutes expected warnings and notices deliberately generated by Smarty
-- [registerCacheResource()](./api-functions/api-register-cacheresource.md) — dynamically register CacheResources
-- [registerClass()](./api-functions/api-register-class.md) — register a class for use in the templates
-- [registerDefaultPluginHandler()](./api-functions/api-register-default-plugin-handler.md) — register a function which gets called on undefined tags
-- [registerFilter()](./api-functions/api-register-filter.md) — dynamically register filters
-- [registerPlugin()](./api-functions/api-register-plugin.md) — dynamically register plugins
-- [registerObject()](./api-functions/api-register-object.md) — register an object for use in the templates
-- [registerResource()](./api-functions/api-register-resource.md) — dynamically register resources
-- [setCacheDir()](./api-functions/api-set-cache-dir.md) — set the directory where the rendered template's output is stored
-- [setCompileDir()](./api-functions/api-set-compile-dir.md) — set the directory where compiled templates are stored
-- [setConfigDir()](./api-functions/api-set-config-dir.md) — set the directories where config files are stored
-- [setPluginsDir()](./api-functions/api-set-plugins-dir.md) — set the directories where plugins are stored
-- [setTemplateDir()](./api-functions/api-set-template-dir.md) — set the directories where templates are stored
-- [templateExists()](./api-functions/api-template-exists.md) — checks whether the specified template exists
-- [unregisterCacheResource()](./api-functions/api-unregister-cacheresource.md) — dynamically unregister a CacheResource plugin
-- [unregisterFilter()](./api-functions/api-unregister-filter.md) — dynamically unregister a filter
-- [unregisterPlugin()](./api-functions/api-unregister-plugin.md) — dynamically unregister plugins
-- [unregisterObject()](./api-functions/api-unregister-object.md) — dynamically unregister an object
-- [unregisterResource()](./api-functions/api-unregister-resource.md) — dynamically unregister a resource plugin
-
-> **Note**
->
-> See
-> [`Changing settings by template`](./advanced-features/advanced-features-template-settings.md)
-> section for how to use the functions for individual templates.
diff --git a/docs/programmers/api-functions/add-extension.md b/docs/programmers/api-functions/add-extension.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/programmers/api-functions/api-add-config-dir.md b/docs/programmers/api-functions/api-add-config-dir.md
deleted file mode 100644
index c3a05228..00000000
--- a/docs/programmers/api-functions/api-add-config-dir.md
+++ /dev/null
@@ -1,49 +0,0 @@
-addConfigDir()
-
-add a directory to the list of directories where config files are stored
-
-Description
-===========
-
-Smarty
-
-addConfigDir
-
-string\|array
-
-config\_dir
-
-string
-
-key
-
-
-    <?php
-
-    // add directory where config files are stored
-    $smarty->addConfigDir('./config_1');
-
-    // add directory where config files are stored and specify array-key
-    $smarty->addConfigDir('./config_1', 'one');
-
-    // add multiple directories where config files are stored and specify array-keys
-    $smarty->addTemplateDir(array(
-        'two' => './config_2',
-        'three' => './config_3',
-    ));
-
-    // view the template dir chain
-    var_dump($smarty->getConfigDir());
-
-    // chaining of method calls
-    $smarty->setConfigDir('./config')
-           ->addConfigDir('./config_1', 'one')
-           ->addConfigDir('./config_2', 'two');
-
-    ?>
-
-       
-
-See also [`getConfigDir()`](#api.get.config.dir),
-[`setConfigDir()`](#api.set.config.dir) and
-[`$config_dir`](#variable.config.dir).
diff --git a/docs/programmers/api-functions/api-add-template-dir.md b/docs/programmers/api-functions/api-add-template-dir.md
deleted file mode 100644
index e0d24564..00000000
--- a/docs/programmers/api-functions/api-add-template-dir.md
+++ /dev/null
@@ -1,49 +0,0 @@
-addTemplateDir()
-
-add a directory to the list of directories where templates are stored
-
-Description
-===========
-
-Smarty
-
-addTemplateDir
-
-string\|array
-
-template\_dir
-
-string
-
-key
-
-
-    <?php
-
-    // add directory where templates are stored
-    $smarty->addTemplateDir('./templates_1');
-
-    // add directory where templates are stored and specify array-key
-    $smarty->addTemplateDir('./templates_1', 'one');
-
-    // add multiple directories where templates are stored and specify array-keys
-    $smarty->addTemplateDir(array(
-        'two' => './templates_2',
-        'three' => './templates_3',
-    ));
-
-    // view the template dir chain
-    var_dump($smarty->getTemplateDir());
-
-    // chaining of method calls
-    $smarty->setTemplateDir('./templates')
-           ->addTemplateDir('./templates_1', 'one')
-           ->addTemplateDir('./templates_2', 'two');
-
-    ?>
-
-       
-
-See also [`getTemplateDir()`](#api.get.template.dir),
-[`setTemplateDir()`](#api.set.template.dir) and
-[`$template_dir`](#variable.template.dir).
diff --git a/docs/programmers/api-functions/api-append-by-ref.md b/docs/programmers/api-functions/api-append-by-ref.md
deleted file mode 100644
index cd396d9c..00000000
--- a/docs/programmers/api-functions/api-append-by-ref.md
+++ /dev/null
@@ -1,46 +0,0 @@
-appendByRef()
-
-append values by reference
-
-Description
-===========
-
-void
-
-appendByRef
-
-string
-
-varname
-
-mixed
-
-var
-
-bool
-
-merge
-
-This is used to [`append()`](#api.append) values to the templates by
-reference.
-
-> **Note**
->
-> With the introduction of PHP5, `appendByRef()` is not necessary for
-> most intents and purposes. `appendByRef()` is useful if you want a PHP
-> array index value to be affected by its reassignment from a template.
-> Assigned object properties behave this way by default.
-
-NOTE.PARAMETER.MERGE
-
-
-    <?php
-    // appending name/value pairs
-    $smarty->appendByRef('Name', $myname);
-    $smarty->appendByRef('Address', $address);
-    ?>
-
-       
-
-See also [`append()`](#api.append), [`assign()`](#api.assign) and
-[`getTemplateVars()`](#api.get.template.vars).
diff --git a/docs/programmers/api-functions/api-append.md b/docs/programmers/api-functions/api-append.md
index b9458641..d9acff84 100644
--- a/docs/programmers/api-functions/api-append.md
+++ b/docs/programmers/api-functions/api-append.md
@@ -56,6 +56,5 @@ NOTE.PARAMETER.MERGE
 
        
 
-See also [`appendByRef()`](#api.append.by.ref),
-[`assign()`](#api.assign) and
+See also [`assign()`](#api.assign) and
 [`getTemplateVars()`](#api.get.template.vars)
diff --git a/docs/programmers/api-functions/api-assign-by-ref.md b/docs/programmers/api-functions/api-assign-by-ref.md
deleted file mode 100644
index 7c42b483..00000000
--- a/docs/programmers/api-functions/api-assign-by-ref.md
+++ /dev/null
@@ -1,42 +0,0 @@
-assignByRef()
-
-assign values by reference
-
-Description
-===========
-
-void
-
-assignByRef
-
-string
-
-varname
-
-mixed
-
-var
-
-This is used to [`assign()`](#api.assign) values to the templates by
-reference.
-
-> **Note**
->
-> With the introduction of PHP5, `assignByRef()` is not necessary for
-> most intents and purposes. `assignByRef()` is useful if you want a PHP
-> array index value to be affected by its reassignment from a template.
-> Assigned object properties behave this way by default.
-
-
-    <?php
-    // passing name/value pairs
-    $smarty->assignByRef('Name', $myname);
-    $smarty->assignByRef('Address', $address);
-    ?>
-
-       
-
-See also [`assign()`](#api.assign),
-[`clearAllAssign()`](#api.clear.all.assign), [`append()`](#api.append),
-[`{assign}`](#language.function.assign) and
-[`getTemplateVars()`](#api.get.template.vars).
diff --git a/docs/programmers/api-functions/api-assign.md b/docs/programmers/api-functions/api-assign.md
index c3b9985d..31f6a150 100644
--- a/docs/programmers/api-functions/api-assign.md
+++ b/docs/programmers/api-functions/api-assign.md
@@ -78,7 +78,6 @@ To access more complex array assignments see
 [`{foreach}`](#language.function.foreach) and
 [`{section}`](#language.function.section)
 
-See also [`assignByRef()`](#api.assign.by.ref),
-[`getTemplateVars()`](#api.get.template.vars),
+See also [`getTemplateVars()`](#api.get.template.vars),
 [`clearAssign()`](#api.clear.assign), [`append()`](#api.append) and
 [`{assign}`](#language.function.assign)
diff --git a/docs/programmers/api-functions/api-get-cache-dir.md b/docs/programmers/api-functions/api-get-cache-dir.md
deleted file mode 100644
index 9e55d8d0..00000000
--- a/docs/programmers/api-functions/api-get-cache-dir.md
+++ /dev/null
@@ -1,23 +0,0 @@
-getCacheDir()
-
-return the directory where the rendered template\'s output is stored
-
-Description
-===========
-
-string
-
-getCacheDir
-
-
-    <?php
-
-    // get directory where compiled templates are stored
-    $cacheDir = $smarty->getCacheDir();
-
-    ?>
-
-       
-
-See also [`setCacheDir()`](#api.set.cache.dir) and
-[`$cache_dir`](#variable.cache.dir).
diff --git a/docs/programmers/api-functions/api-get-compile-dir.md b/docs/programmers/api-functions/api-get-compile-dir.md
deleted file mode 100644
index 3bfae730..00000000
--- a/docs/programmers/api-functions/api-get-compile-dir.md
+++ /dev/null
@@ -1,23 +0,0 @@
-getCompileDir()
-
-returns the directory where compiled templates are stored
-
-Description
-===========
-
-string
-
-getCompileDir
-
-
-    <?php
-
-    // get directory where compiled templates are stored
-    $compileDir = $smarty->getCompileDir();
-
-    ?>
-
-       
-
-See also [`setCompileDir()`](#api.set.compile.dir) and
-[`$compile_dir`](#variable.compile.dir).
diff --git a/docs/programmers/api-functions/api-get-template-dir.md b/docs/programmers/api-functions/api-get-template-dir.md
deleted file mode 100644
index 42c75908..00000000
--- a/docs/programmers/api-functions/api-get-template-dir.md
+++ /dev/null
@@ -1,40 +0,0 @@
-getTemplateDir()
-
-return the directory where templates are stored
-
-Description
-===========
-
-string\|array
-
-getTemplateDir
-
-string
-
-key
-
-
-    <?php
-
-    // set some template directories
-    $smarty->setTemplateDir(array(
-        'one' => './templates',
-        'two' => './templates_2',
-        'three' => './templates_3',
-    ));
-
-    // get all directories where templates are stored
-    $template_dir = $smarty->getTemplateDir();
-    var_dump($template_dir); // array
-
-    // get directory identified by key
-    $template_dir = $smarty->getTemplateDir('one');
-    var_dump($template_dir); // string
-
-    ?>
-
-       
-
-See also [`setTemplateDir()`](#api.set.template.dir),
-[`addTemplateDir()`](#api.add.template.dir) and
-[`$template_dir`](#variable.template.dir).
diff --git a/docs/programmers/api-functions/api-set-cache-dir.md b/docs/programmers/api-functions/api-set-cache-dir.md
deleted file mode 100644
index 7f7c4b60..00000000
--- a/docs/programmers/api-functions/api-set-cache-dir.md
+++ /dev/null
@@ -1,32 +0,0 @@
-setCacheDir()
-
-set the directory where the rendered template\'s output is stored
-
-Description
-===========
-
-Smarty
-
-setCacheDir
-
-string
-
-cache\_dir
-
-
-    <?php
-
-    // set directory where rendered template's output is stored
-    $smarty->setCacheDir('./cache');
-
-    // chaining of method calls
-    $smarty->setTemplateDir('./templates')
-           ->setCompileDir('./templates_c')
-           ->setCacheDir('./cache');
-
-    ?>
-
-       
-
-See also [`getCacheDir()`](#api.get.cache.dir) and
-[`$cache_dir`](#variable.cache.dir).
diff --git a/docs/programmers/api-functions/api-set-compile-dir.md b/docs/programmers/api-functions/api-set-compile-dir.md
deleted file mode 100644
index bfeb55a5..00000000
--- a/docs/programmers/api-functions/api-set-compile-dir.md
+++ /dev/null
@@ -1,32 +0,0 @@
-setCompileDir()
-
-set the directory where compiled templates are stored
-
-Description
-===========
-
-Smarty
-
-setCompileDir
-
-string
-
-compile\_dir
-
-
-    <?php
-
-    // set directory where compiled templates are stored
-    $smarty->setCompileDir('./templates_c');
-
-    // chaining of method calls
-    $smarty->setTemplateDir('./templates')
-           ->setCompileDir('./templates_c')
-           ->setCacheDir('./cache');
-
-    ?>
-
-       
-
-See also [`getCompileDir()`](#api.get.compile.dir) and
-[`$compile_dir`](#variable.compile.dir).
diff --git a/docs/programmers/api-functions/api-set-config-dir.md b/docs/programmers/api-functions/api-set-config-dir.md
deleted file mode 100644
index 97a6ae97..00000000
--- a/docs/programmers/api-functions/api-set-config-dir.md
+++ /dev/null
@@ -1,47 +0,0 @@
-setConfigDir()
-
-set the directories where config files are stored
-
-Description
-===========
-
-Smarty
-
-setConfigDir
-
-string\|array
-
-config\_dir
-
-
-    <?php
-
-    // set a single directory where the config files are stored
-    $smarty->setConfigDir('./config');
-
-    // view the config dir chain
-    var_dump($smarty->getConfigDir());
-
-    // set multiple directoríes where config files are stored
-    $smarty->setConfigDir(array(
-        'one' => './config',
-        'two' => './config_2',
-        'three' => './config_3',
-    ));
-
-    // view the config dir chain
-    var_dump($smarty->getConfigDir());
-
-    // chaining of method calls
-    $smarty->setTemplateDir('./templates')
-           ->setConfigDir('./config')
-           ->setCompileDir('./templates_c')
-           ->setCacheDir('./cache');
-
-    ?>
-
-       
-
-See also [`getConfigDir()`](#api.get.config.dir),
-[`addConfigDir()`](#api.add.config.dir) and
-[`$config_dir`](#variable.config.dir).
diff --git a/docs/programmers/api-functions/api-set-template-dir.md b/docs/programmers/api-functions/api-set-template-dir.md
deleted file mode 100644
index 2de23309..00000000
--- a/docs/programmers/api-functions/api-set-template-dir.md
+++ /dev/null
@@ -1,46 +0,0 @@
-setTemplateDir()
-
-set the directories where templates are stored
-
-Description
-===========
-
-Smarty
-
-setTemplateDir
-
-string\|array
-
-template\_dir
-
-
-    <?php
-
-    // set a single directory where the templates are stored
-    $smarty->setTemplateDir('./cache');
-
-    // view the template dir chain
-    var_dump($smarty->getTemplateDir());
-
-    // set multiple directoríes where templates are stored
-    $smarty->setTemplateDir(array(
-        'one' => './templates',
-        'two' => './templates_2',
-        'three' => './templates_3',
-    ));
-
-    // view the template dir chain
-    var_dump($smarty->getTemplateDir());
-
-    // chaining of method calls
-    $smarty->setTemplateDir('./templates')
-           ->setCompileDir('./templates_c')
-           ->setCacheDir('./cache');
-
-    ?>
-
-       
-
-See also [`getTemplateDir()`](#api.get.template.dir),
-[`addTemplateDir()`](#api.add.template.dir) and
-[`$template_dir`](#variable.template.dir).
diff --git a/docs/programmers/api-variables.md b/docs/programmers/api-variables.md
deleted file mode 100644
index 17aae55a..00000000
--- a/docs/programmers/api-variables.md
+++ /dev/null
@@ -1,57 +0,0 @@
-Smarty Class Variables {#api.variables}
-======================
-
-These are all of the available Smarty class variables. You can access
-them directly, or use the corresponding setter/getter methods.
-
-- [$auto_literal](./api-variables/variable-auto-literal.md)
-- [$cache_dir](./api-variables/variable-cache-dir.md)
-- [$cache_id](./api-variables/variable-cache-id.md)
-- [$cache_lifetime](./api-variables/variable-cache-lifetime.md)
-- [$cache_locking](./api-variables/variable-cache-locking.md)
-- [$cache_modified_check](./api-variables/variable-cache-modified-check.md)
-- [$caching](./api-variables/variable-caching.md)
-- [$caching_type](./api-variables/variable-caching-type.md)
-- [$compile_check](./api-variables/variable-compile-check.md)
-- [$compile_dir](./api-variables/variable-compile-dir.md)
-- [$compile_id](./api-variables/variable-compile-id.md)
-- [$compile_locking](./api-variables/variable-compile-locking.md)
-- [$compiler_class](./api-variables/variable-compiler-class.md)
-- [$config_booleanize](./api-variables/variable-config-booleanize.md)
-- [$config_dir](./api-variables/variable-config-dir.md)
-- [$config_overwrite](./api-variables/variable-config-overwrite.md)
-- [$config_read_hidden](./api-variables/variable-config-read-hidden.md)
-- [$debug_tpl](./api-variables/variable-debug-template.md)
-- [$debugging](./api-variables/variable-debugging.md)
-- [$debugging_ctrl](./api-variables/variable-debugging-ctrl.md)
-- [$default_config_type](./api-variables/variable-default-config-type.md)
-- [$default_modifiers](./api-variables/variable-default-modifiers.md)
-- [$default_resource_type](./api-variables/variable-default-resource-type.md)
-- [$default_config_handler_func](./api-variables/variable-default-config-handler-func.md)
-- [$default_template_handler_func](./api-variables/variable-default-template-handler-func.md)
-- [$error_reporting](./api-variables/variable-error-reporting.md)
-- [$escape_html](./api-variables/variable-escape-html.md)
-- [$force_cache](./api-variables/variable-force-cache.md)
-- [$force_compile](./api-variables/variable-force-compile.md)
-- [$left_delimiter](./api-variables/variable-left-delimiter.md)
-- [$locking_timeout](./api-variables/variable-locking-timeout.md)
-- [$merge_compiled_includes](./api-variables/variable-merge-compiled-includes.md)
-- [$right_delimiter](./api-variables/variable-right-delimiter.md)
-- [$smarty_debug_id](./api-variables/variable-smarty-debug-id.md)
-- [$template_dir](./api-variables/variable-template-dir.md)
-- [$use_sub_dirs](./api-variables/variable-use-sub-dirs.md)
-
-> **Note**
->
-> All class variables have magic setter/getter methods available.
-> setter/getter methods are camelCaseFormat, unlike the variable itself.
-> So for example, you can set and get the \$smarty-\>template\_dir
-> variable with \$smarty-\>setTemplateDir(\$dir) and \$dir =
-> \$smarty-\>getTemplateDir() respectively.
-
-> **Note**
->
-> See
-> [`Changing settings by template`](./advanced-features/advanced-features-template-settings.md)
-> section for how to change Smarty class variables for individual
-> templates.
diff --git a/docs/programmers/charset.md b/docs/programmers/charset.md
deleted file mode 100644
index cec7a966..00000000
--- a/docs/programmers/charset.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# Charset Encoding
-
-There are a variety of encodings for textual data, ISO-8859-1 (Latin1)
-and UTF-8 being the most popular. Unless you change `\Smarty\Smarty::$_CHARSET`, 
-Smarty recognizes `UTF-8` as the internal charset.
-
-> **Note**
->
-> `ISO-8859-1` has been PHP\'s default internal charset since the
-> beginning. Unicode has been evolving since 1991. Since then it has
-> become the one charset to conquer them all, as it is capable of
-> encoding most of the known characters even across different character
-> systems (latin, cyrillic, japanese, ...). `UTF-8` is unicode\'s most
-> used encoding, as it allows referencing the thousands of character
-> with the smallest size overhead possible.
->
-> Since unicode and UTF-8 are very wide spread nowadays, their use is
-> strongly encouraged.
-
-> **Note**
->
-> Smarty\'s internals and core plugins are truly UTF-8 compatible since
-> Smarty 3.1.
-
-```php
-<?php
-    
-// use japanese character encoding
-mb_internal_charset('EUC-JP');
-
-\Smarty\Smarty::$_CHARSET = 'EUC-JP';
-$smarty = new \Smarty\Smarty();
-
-```
-     
diff --git a/mkdocs.yml b/mkdocs.yml
index 7762cd75..71909647 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -11,7 +11,7 @@ theme:
     - navigation.tracking
   icon:
     logo: material/lightbulb-on
-  favicon: images/favicon.ico
+  favicon: img/favicon.ico
 
 extra:
   version:
@@ -27,7 +27,7 @@ markdown_extensions:
 nav:
   - Home: 'index.md'
   - 'Getting started': 'getting-started.md'
-  - 'Designers':
+  - 'Language reference':
     - 'Basic Syntax':
         - Introduction: 'designers/language-basic-syntax/index.md'
         - Comments: 'designers/language-basic-syntax/language-syntax-comments.md'
@@ -69,7 +69,7 @@ nav:
         - 'unescape': 'designers/language-modifiers/language-modifier-unescape.md'
         - 'upper': 'designers/language-modifiers/language-modifier-upper.md'
         - 'wordwrap': 'designers/language-modifiers/language-modifier-wordwrap.md'
-    - 'designers/language-combining-modifiers.md'
+    - 'Combining Modifiers': 'designers/language-combining-modifiers.md'
     - 'Builtin Functions':
         - 'Introduction': 'designers/language-builtin-functions/index.md'
         - '{append}': 'designers/language-builtin-functions/language-function-append.md'
@@ -112,12 +112,30 @@ nav:
         - '{textformat}': 'designers/language-custom-functions/language-function-textformat.md'
     - 'designers/config-files.md'
     - 'designers/chapter-debugging-console.md'
-  - 'Programmers':
-      - 'programmers/charset.md'
-      - 'programmers/smarty-constants.md'
-      - 'programmers/api-variables.md'
-      - 'programmers/api-functions.md'
-      - 'programmers/caching.md'
-      - 'programmers/resources.md'
-      - 'programmers/advanced-features.md'
-      - 'programmers/plugins.md'
\ No newline at end of file
+  - 'API':
+      - 'Basics': 'api/basics.md'
+      - 'Configuring Smarty': 'api/configuring.md'
+      - 'Rendering a template': 'api/rendering.md'
+      - 'Using data in templates':
+          - 'Assigning variables': 'api/variables/assigning.md'
+          - 'Loading from config files': 'api/variables/config-files.md'
+          - 'Using streams': 'api/variables/streams.md'
+          - 'Objects': 'api/variables/objects.md'
+          - 'Static class methods': 'api/variables/static-class-methods.md'
+      - 'Template inheritance': 'api/inheritance.md'
+      - 'Caching':
+        - 'Basics': 'api/caching/basics.md'
+        - 'Multiple caches per page': 'api/caching/multiple-caches-per-pages.md'
+        - 'Custom cache storage layers': 'api/caching/custom-storage-layers.md'
+      - 'Security': 'api/security.md'
+      - 'Extending Smarty':
+          - 'Introduction': 'api/extending/introduction.md'
+          - 'Creating an Extension': 'api/extending/extensions.md'
+          - 'Custom tags': 'api/extending/tags.md'
+          - 'Custom block tags': 'api/extending/block-tags.md'
+          - 'Custom modifiers': 'api/extending/modifiers.md'
+      - 'Filters':
+          - 'Prefilters': 'api/filters/prefilters.md'
+          - 'Postfilters': 'api/filters/postfilters.md'
+          - 'Output filters': 'api/filters/output-filters.md'
+      - 'Loading templates from resources': 'api/resources.md'