diff --git a/docs/framework/templates/customizing.md b/docs/framework/templates/customizing.md
new file mode 100644
index 0000000000000000000000000000000000000000..c6653e498d4a92b80b6e9687b19f982ea76dae72
--- /dev/null
+++ b/docs/framework/templates/customizing.md
@@ -0,0 +1,411 @@
+# Customizing Built-in Screens
+
+!!! caution "Use extensions instead"
+
+    The methods on this page are of historical interest and may be helpful in understanding legacy code, but overriding templates and php files is strongly discouraged for any new customisations. These approaches need attention whenever you upgrade and will cause a range of problems from subtle to major if you forget about them.
+    
+    As CiviCRM evolves, the recommended ways of customizing it change.   The current preferred method is to Create an Extension to implement Hooks and use the API.  If you can't find a way to use existing hooks to accomplish what you want, discuss it on StackExchange or Chat.  It may be appropriate to add a new hook to core.
+    
+    (It is possible to override templates and php in an extension, but you face the same problems when it comes to upgrading - don't do it!)
+
+
+You can create customized versions of the standard CiviCRM
+forms and pages for your site. This gives you a lot of power to modify
+the CiviCRM user interfaces without requiring advanced programming
+skills - the templates use HTML plus a fairly simple scripting language.
+It also means you won't lose your customizations when you upgrade
+(although it is possible that changes in the core code could affect your
+templates - and testing after upgrades is essential).
+
+## First Time Configuration
+
+-   Create a new directory under your webroot (or anywhere readable
+    by www-data) where you will place your custom template files.
+    -   EX: `/var/www/civicrm_custom`
+    -   EX: `/var/www/media/civicrm/customtpl/`
+-   Login to CiviCRM with administer CiviCRM permissions and navigate to
+    **Administer CiviCRM » Global Settings » Directories** (in newer
+    versions this is Administer » System settings » Directories)
+-   Enter the full path to your custom templates directory in the
+    **Custom Templates** field and save your changes.
+
+## Create a Custom Screen
+
+These steps are for any "built-in" screen (e.g. the **Contact Summary**
+screen). Creating a custom **Profile** form or page are covered in the
+next section.
+
+-   Navigate to the screen you want to customize and use your browser to **View Source**.
+-   Search for `.tpl` in the source. You will find a comment line which gives you the path and name of the template used for the screen you are viewing.
+    
+    ```html
+    <!-- .tpl file invoked: CRM/Contact/Page/View/Summary.tpl. Call via form.tpl if we have a form in the page. -->
+    ```
+
+-   Locate this file on your server under your `civicrm/templates` path.
+-   Make a copy of file in the equivalent path under your new custom templates directory.
+
+    If your civicrm install files are in: `/var/www/drupal/sites/all/modules/civicrm`  ...and your custom templates directory is:  `/var/www/civicrm_custom`
+    
+    Create directory structure in your custom templates tree
+    
+    ```bash
+    $ cd /var/www/civicrm_custom
+    $ mkdir CRM
+    $ cd CRM
+    $ mkdir Contact
+    $ cd Contact
+    $ mkdir Page
+    $ cd Page
+    $ mkdir View
+    $ cd View
+    ```
+    
+    -OR-, do all of the above with:
+    
+    ```html
+    $ mkdir -p CRM/Contact/Page/View/ ; cd CRM/Contact/Page/View/
+    ```
+   
+    Copy standard template to your new tree
+
+    ```bash
+    $ cp /var/www/drupal/sites/all/modules/civicrm/templates/CRM/Contact/Page/View/Summary.tpl
+    ```
+    
+
+-   Edit the file as needed and save.
+-   Then clean-up the **compiled templates directory**, usually by deleting all the directories under your `templates_c` directory. You can also do the cleanup by enabling CiviCRM debugging and running the directory cleanup command.
+    
+    !!! note
+        You do NOT need to delete the standard version of the template from your main CiviCRM codebase. CiviCRM will look for a customized version first, and use that one if found.)
+        
+-   You should see your modified version when you reload the
+    CiviCRM screen.
+    -   If you need help with the templating language, check out the [Smarty Documentation](http://www.smarty.net/)
+
+## Create a Custom Screen for Contact SubTypes
+
+You can have customized view/edit screens for contact subtypes in CiviCRM. This allows you to have different views for your specific contact subtypes. 
+
+
+If your civicrm install files are in:
+`/var/www/drupal/sites/all/modules/civicrm`
+...and your custom templates directory is:
+`/var/www/civicrm_custom`
+
+Create a directory "SubType" to place your custom contact subtypes
+
+```bash
+$ mkdir SubType
+``` 
+
+The new directory structure is:
+
+* `/var/www/civicrm_custom/CRM/Contact/Form/Edit/SubType/`
+* `/var/www/civicrm_custom/CRM/Contact/Page/View/SubType/`
+
+To override edit screen: put `subTypeName.tpl` file in the `templates/CRM/Contact/Form/Edit/SubType/` directory.
+
+To override view screen(contact summary): put `subTypeName.tpl` file in the `templates/CRM/Contact/Page/View/SubType/` directory.
+
+For Example if you want to create custom templates for Contact SubTypes "Student" and "Sponsor". Copy standard template to your new tree as:
+
+For Contact SubType "Student"
+
+* Edit Screen
+
+    ```bash
+    $ cp /var/www/drupal/sites/all/modules/civicrm/templates/CRM/Contact/Form/Contact.tpl
+               /var/www/drupal/sites/all/modules/civicrm/civicrm_custom/CRM/Contact/Form/Edit/SubType/Student.tpl
+    ```
+
+* View Screen
+
+    ```bash
+    $ cp /var/www/drupal/sites/all/modules/civicrm/templates/CRM/Contact/Page/View/Summary.tpl
+               /var/www/drupal/sites/all/modules/civicrm/civicrm_custom/CRM/Contact/Page/View/SubType/Student.tpl
+    ```
+
+For Contact SubType "Sponsor"
+
+* Edit Screen
+
+    ```bash
+    $ cp /var/www/drupal/sites/all/modules/civicrm/templates/CRM/Contact/Form/Contact.tpl
+               /var/www/drupal/sites/all/modules/civicrm/civicrm_custom/CRM/Contact/Form/Edit/SubType/Sponsor.tpl
+    ```
+
+* View Screen
+
+    ```bash
+    $ cp /var/www/drupal/sites/all/modules/civicrm/templates/CRM/Contact/Page/View/Summary.tpl
+               /var/www/drupal/sites/all/modules/civicrm/civicrm_custom/CRM/Contact/Page/View/SubType/Sponsor.tpl
+    ```
+
+Edit the file as needed and save.
+
+Then clean-up the **compiled templates directory**, usually by
+deleting all the directories under your templates_c directory. You
+can also do the cleanup by [enabling CiviCRM debugging and running
+the directory cleanup command](#){.unresolved}. (NOTE: You do NOT
+need to delete the standard version of the template from your main
+CiviCRM codebase. CiviCRM will look for a customized version first,
+and use that one if found.)
+
+You should see your modified version when you reload the CiviCRM screen.
+    
+If you need help with the templating language, check out the [Smarty Documentation](http://www.smarty.net/)
+
+## Custom Profile / Contribution / Event Registration Screens
+
+The process for customizing Profiles / Contribution / Event Registration
+is the same as above EXCEPT that you have the flexibility to create
+different screen "versions" for each of your configured Profile /
+Contribution / Event Registration Pages. The structure for contribution
+and event registration pages is similar to that of profile explained
+here. You do this by creating an extra directory layer in your custom
+directory tree that references the Profile's **ID**.
+
+
+!!! tip
+    If you want a custom version of the **Profile View** screen for a Profile whose ID is 2...and your basic install and custom directory setup are the same as shown above - then your custom template copy should be saved to:
+
+        /var/www/civicrm_custom/CRM/Profile/Page/2/View.tpl
+
+
+!!! tip
+    If you want a custom version of the Profile Create/Edit screen for a Profile whose ID is 2...and your basic install and custom directory setup are the same as shown above - then your custom template copy should be saved to:
+
+        /var/www/civicrm_custom/CRM/Profile/Form/2/Edit.tpl
+
+
+Profile ID's are listed in the Administer CiviCRM » CiviCRM Profiles table (ID column).
+
+
+!!! tip
+    If you want a custom version of the **Register** screen for an **Event** whose ID is 2...and your basic install and custom directory setup are the same as shown above - then your custom template copy should be saved to:
+
+        /var/www/civicrm_custom/CRM/Event/Form/Registration/2/Register.tpl
+
+Customizing `MembershipBlock.tpl`.
+
+If you are making customizations for specific contribution forms based on the ID, you will need to also customize the `Main.tpl` file to call your custom `MembershipBlock.tpl` file.
+
+In `Main.tpl` in your custom template directory find:
+
+```smarty
+{include file="CRM/Contribute/Form/Contribution/MembershipBlock.tpl" context="makeContribution"}
+```
+
+and change it to:
+
+```smarty
+{include file="CRM/Contribute/Form/Contribution/1/MembershipBlock.tpl" context="makeContribution"}
+```
+
+insuring that you are using the correct path for your custom form id.
+
+### Referencing Individual Fields in Profile Pages
+
+Profile view and edit pages consist of several template files working
+together. The View.tpl (detail view pages) and `Edit.tpl` (edit pages)
+each reference a corresponding Dynamic.tpl file, which cycles through
+the fields found in the profile and displays them in a table. The layout
+is very basic -- one column is used for the field label, the other
+column for the field value or form field. Often, when customizing
+profile pages, you may want to reference specific fields and layout them
+out in a customized display. To do so you would work with the
+`View.tpl`/`Edit.tpl` files and insert smarty tokens for the profile fields
+array. The profile fields array is structured as follows:
+
+-   `$profileFields_ProfileID => Field Name => label/value`
+
+So you would insert the following token into the template file to
+reference the First Name label and field value in Profile 3:
+
+-   `{$profileFields_3.first_name.label}: {$profileFields_3.first_name.value}`
+
+Custom fields in your profile are referenced using the custom ID value,
+e.g. `{$profileFields_3.custom_38.value}`.
+
+To customize fields displayed within Drupal profiles, edit Dynamic.tpl
+and use `$profileFields => Field Name => label/value` (e.g.
+`{$profileFields.first_name.value}` - without the profile ID) to
+reference individual profile fields.
+
+!!! tip
+    With debugging turned on, use the Smarty Debug url string to view the Smarty variables available for inclusion on any given page. Add `&smartyDebug=1` at the end of your page url.
+
+
+## Changing Show/Hide Default on Collapsible Fieldsets
+
+In the words of Dave Greenberg:
+
+> This is a bit tricky because the
+collapse vs. expand states are controlled via showBlocks and hideBlocks
+arrays that are passed into a jscript function by the PHP code.
+
+So I will show you how to do this using an example.
+
+If you want to make a fieldset that is by default collapsible or hidden
+on a CiviCRM Contact View screen, you would need to follow all the above
+instructions to first get the correct custom template and put it in the
+proper location. Let's assume you want to edit the
+`CRM/Contact/Page/View/Tabbed.tpl` screen, which is the default contact
+view. You would copy that into your custom template location. Then you
+will need to determine the name of the fieldset that you want to change
+the default state of. Let's say I want to collapse the "Communications
+Preferences" fieldset by default. Look in the file for that section, so
+in this case I find the line that has the following:
+
+```html
+<a href="#"
+    onclick="hide('commPrefs_show'); show('commPrefs'); return false;">
+  <img
+      src="{$config->resourceBase}i/TreePlus.gif" 
+      class="action-icon"
+      alt="{ts}open section{/ts}"/>
+</a>
+<label>{ts}Communications Preferences{/ts}</label>
+```
+
+We can see that there's a javascript onclick call which references
+`'commPrefs_show'` and `'commPrefs'`. So since this fieldset is by default
+showing up, we need to force the javascript to reverse it. So next you
+need to scroll to the bottom of this file and look for the following
+javascript call:
+
+```smarty
+{literal}
+ <script type="text/javascript">
+
+   init_blocks = function( ) {
+{/literal}
+      var showBlocks = new Array({$showBlocks});
+      var hideBlocks = new Array({$hideBlocks});
+{literal}
+      on_load_init_blocks( showBlocks, hideBlocks );
+  }
+
+  dojo.addOnLoad( init_blocks );
+ </script>
+{/literal}
+```
+
+The way we will fix this is to reverse the hide/show states of
+Communication Preferences. We will add the following two lines after
+`on_load_init_blocks(showBlocks, hideBlocks)`;
+
+```javascript
+hide('commPrefs');
+show('commPrefs_show');
+```
+
+And that will fix it. Our final javascript call will look like this:
+
+```smarty
+{literal}
+ <script type="text/javascript">
+
+   init_blocks = function( ) {
+{/literal}
+      var showBlocks = new Array({$showBlocks});
+      var hideBlocks = new Array({$hideBlocks});
+{literal}
+      on_load_init_blocks( showBlocks, hideBlocks );
+      // Added next 2 lines to reverse the show and hide states for commPrefs blocks
+      hide('commPrefs');
+      show('commPrefs_show');
+  }
+
+  dojo.addOnLoad( init_blocks );
+ </script>
+{/literal}
+```
+
+So for any other fieldset, you can find the show/hide names by looking
+for the fieldset section in the code as I demonstrated here. Just look
+at the `<a>` tag for the onclick function.
+
+## Using jQuery to hide contribution amounts, event fees, or membership options
+
+It's pretty easy to do, but the key is identifying the unique 'id' of
+the radio button of the item you wish to hide.
+
+Use [Firebug](http://getfirebug.com) to click on the
+radio button and copy and paste the id number. The ids are cryptic and
+will look something like this example: `CIVICRM_QFID_369_2`
+
+Then use some jQuery. You can put this jQuery in one of three places.
+1. a unfiltered block that is visible on the page in question (Drupal only)
+2. in your site's theme files
+3. in a custom .tpl in a Custom Template Directory in CiviCRM as described on this page
+
+Here is an example of the jQuery code.
+
+!!! note
+    there is no need to use `drupal_add_js()` or any other function.
+    This is just pure jQuery code. Copy and paste, filling in the id of your
+    field where indicated
+
+This jQuery does 3 things: Hides the radio button itself, hides the
+label, and hides the `<br>` tag immediately after the label. So
+easy.
+
+```smarty
+{literal}
+<script>
+  cj("#YOUR_CIVICRM_QFID_999_9").hide();
+  cj("label[for='YOUR_CIVICRM_QFID_999_9']").next('br').remove();
+  cj("label[for='YOUR_CIVICRM_QFID_999_9']").hide();
+</script>
+{/literal}
+```
+
+
+If you are using option #3 above you can use this jQuery in conjunction
+with `$user->roles;` array to hide certain options for certain roles
+only.
+
+## Move the placement of hook form elements
+
+When defining CiviCRM fields in a Drupal module (such as [Civievent
+Discount](http://drupal.org/project/civievent_discount)),
+CiviCRM normally will place the fields at the top of the form. If you
+want the placement changed, follow these steps.
+
+1.  Set the path for custom templates in CiviCRM (see above).
+2.  Make a custom version of `CRM/Form/body.tpl` at
+    `custom_civicrm_templates/CRM/Form/body.tpl` (or wherever you place
+    the custom templates).
+3.  Cut everything between the
+
+    ```smarty
+    {if $beginHookFormElements}
+    ```
+        
+    and
+
+    ```smarty
+    {/if}
+    ```
+
+1.  Create a new custom template at `CRM/common` called
+    `hookFormElements.tpl`
+2.  Insert the `$beginHookFormElements` text from `body.tpl`
+3.  Create custom version of `CRM/Contribute/Form/Contribution/Main.tpl`
+    (for memberships) and `CRM/Event/Form/Registration/Register.tpl`
+    (for events).
+4.  Place this snippet:
+
+    ```smarty
+    {include file="CRM/common/hookFormElements.tpl"}
+    ```
+
+    wherever you want it to appear in the template. Include wherever
+    `body.tpl` is also referenced.
+
+5.  Refresh the template files. Turn debugging on (**Administer >
+    Configure > Global Settings > Debugging**) and then put this at
+    end of URL: `&directoryCleanup=1`, press enter to refresh page.
diff --git a/docs/framework/templates/extending-smarty.md b/docs/framework/templates/extending-smarty.md
new file mode 100644
index 0000000000000000000000000000000000000000..c62795f68cc011ff6f013786bc2799efa2a05ad3
--- /dev/null
+++ b/docs/framework/templates/extending-smarty.md
@@ -0,0 +1,39 @@
+# Extending Smarty
+
+The Smarty templating language that is used to output the HTML for
+CiviCRM's templates is fairly powerful in its own right, but sometimes
+it can't do everything you want.  Smarty can be extended using "plugins"
+-- you can find some examples and documentation online at [Smarty's website](http://www.smarty.net) or by searching the web.
+
+To install Smarty plugins without editing CiviCRM core (which is
+difficult to maintain), you will have to implement 
+[hook_civicrm_config](/hooks/hook_civicrm_config.md).
+
+Once you've created your module or hook file, you can retrieve the
+Smarty object and register your custom plugin path:
+
+```php
+function yourmodule_civicrm_config(&$config) {
+  $smarty = CRM_Core_Smarty::singleton();
+  array_push($smarty->plugins_dir, __DIR__ . '/relative/path/to/custom/plugin/directory');
+}
+```
+
+Then in that custom plugin directory, you can place whatever Smarty
+plugins you need.
+
+You can also use this trick to change other Smarty behavior, such as
+whether it can evaluate PHP placed directly in templates. For instance:
+
+```php
+function yourmodule_civicrm_config(&$config) {
+  $smarty = CRM_Core_Smarty::singleton();
+  
+  // allow the explode() php function to be used as a "modifier" in Smarty templates
+  array_push($smarty->security_settings['MODIFIER_FUNCS'], 'explode'); 
+}
+```
+
+However, be very careful with these settings – if you don't know what
+you're doing, you can open security holes or create a mess of code
+that's difficult to maintain.
diff --git a/docs/framework/templates/index.md b/docs/framework/templates/index.md
new file mode 100644
index 0000000000000000000000000000000000000000..06be0da93cb87a7d22aa28c4d414eeddca5d8aa0
--- /dev/null
+++ b/docs/framework/templates/index.md
@@ -0,0 +1,278 @@
+# Page Templates
+
+!!! warning
+    The content in this page was written at some unknown time prior to 2013. It needs updating and may contain inaccuracies. 
+
+CiviCRM uses page template files to display all the pages. This makes it
+possible for a person to customize any CiviCRM screen to suit a special
+requirement or preference. The HTML for CiviCRM pages is not embedded in
+PHP code, instead a template engine (Smarty) sends the correct page to
+the web browser.
+
+You should be familiar with HTML and CSS syntax to be comfortable
+editing page templates.  Some page templates additionally make use of
+JavaScript and an Ajax utility, JQuery.
+
+## Changing page templates is the wrong choice when ...
+
+1.  it is possible to make the needed changes by updating the
+    CSS styles. For example, if a requirement is to hide or move some
+    information or form fields on a screen, a CSS style for that HTML
+    element can be changed to display: none, or position: absolute
+    within the CSS file.
+2.  there is a CiviCRM hook available that can control the page. For
+    example, there is a hook that can modify the information on the
+    Contact Summary screen
+3.  there is no process in place to update the page templates after an
+    upgrade to a new version of CiviCRM. Page templates are stored in a
+    separate folder and are not touched during an upgrade, However new
+    versions of CiviCRM often change which placeholder elements are
+    available in various templates. Proper source control procedures are
+    needed to simplify upgrades to new versions.
+
+## Smarty templates introduction
+
+CiviCRM uses a page template engine called Smarty.  This documentation
+is focused on how Smarty is used within the CiviCRM environment.  Every
+Smarty element is enclosed between braces like these: `{}`. All the
+other text is going to be displayed directly as HTML in the rendered
+page.
+
+Each page template is stored in a file with the extension `.tpl`. The
+PHP code assigns variables for content that needs to be displayed, and
+then lets the template engine take care of presenting it.
+
+The Smarty template engine always does this process :
+
+1.  Load the contents of a `.tpl` file.
+2.  Scan the `.tpl` file for placeholder elements.
+3.  Replace each placeholder element with the corresponding
+    variable value.
+4.  Send the resulting HTML to the web browser.
+
+These are the most commonly used Smarty template elements:
+
+-   `{$Name}`: To display the value of a variable named "Name"
+-   `{$row.Name}`: To display the value of the attribute Name in the
+    object Row
+-   `{foreach from=$rows item=row}...{/foreach}`: To loop though all the
+    items of the Rows array
+-   `{literal} JavaScript code{/literal}` to indicate to Smarty the `{}`
+    aren't smarty elements but JavaScript code, enclose JavaScript
+    between `{literal}`
+-   `{ldelim}` and `{rdelim}` are alternative
+    ways to generate `{` and `}`.  This is often useful if you have a simple
+    JavaScript code that needs a lot of values from Smarty
+    variables 
+-   `{include file="CRM/path/to/template.tpl" param1=xxx}`: includes the
+    result of the `template.tpl`. Some included files expect to have
+    extra param (e.g., `param1`).
+
+Please read the Smarty documentation for more information.
+
+!!! tip
+    To see what variables have been assigned to the template, enable debug (Administer > Configure > Global Settings > Debugging) and on any URL, add `&smartyDebug=1`. It opens a new browser window listing all the variables and values.
+ 
+CiviCRM introduces some extra features to Smarty:
+
+-   `{ts}Any text{/ts}`: It will display the translated text (if you don't
+    use US English)
+-   ``{crmURL p='civicrm/contact/view' q="reset=1&cid=`$row.source_contact_id`"}``.
+    Generates the proper CiviCRM URL that works both on Joomla!
+    and Drupal.
+-   `{crmAPI}` Allows retrieval and display of extra data that is not
+    assigned to the template already. Read about the CiviCRM API  for
+    more information.
+
+## How to find and modify the templates?
+
+All the templates are under the folder `templates/CRM` in your CiviCRM
+installation. Finding which template is used on a given page can be
+difficult, but the easiest way to find out the answer is to view the
+source of the page from a web browser and search for `.tpl`. For
+example, for the Contact Summary page, use the web browser to open the
+Contact Summary page, then click "View Source" in the browser.  You
+should find an HTML comment such as:
+
+```html
+<!-- .tpl file invoked: CRM/Contact/Page/View/Summary.tpl.   Call via form.tpl if we have a form in the page. -->
+```
+
+You can then view the file at
+`templates/CRM/Contact/Page/View/Summary.tpl` to see how the HTML is
+generated. If you want to modify the layout; for instance to reorder the
+content, do **not** modify directly these files, as all the
+modifications will be lost on the next upgrade of CiviCRM. The proper
+way is to create a new folder outside of your CiviCRM folder, then
+navigate to **Administer -> Configure -> Global settings ->
+Directories** in the navigation menu, and set the complete path of the
+folder that is going to contain your custom templates in the field
+*Custom Templates*.
+
+## Scenario: The Contact Summary screen needs to be changed
+
+If you want to alter the Contact Summary page template for Acme
+organization, perform these steps:
+
+1.  Create the folder
+    `/var/www/civi.custom/acme/templates/CRM/Contact/Page/View`
+2.  Update the Custom Template field in the Global Settings directories
+    to `/var/www/civi.custom/acme/templates.` You can use any directory.
+    We found it easier to put the custom templates under
+    `/var/www/civi.custom/yourorganisation`.
+3.  copy `templates/Contact/Page/View/Summary.tpl` from your CiviCRM
+    install to `/var/www/civi.custom/acme`
+
+!!! tip
+    Say you want to modify the template for a specific profile form, or a specific event. Instead of copying the Form template to its default place (`templates/CRM/Profile/Form/Edit.tpl`), you can create a subfolder with the ID of the profile and put the template file you want to change in the subfolder (`templates/CRM/Profile/Form/42/Edit.tpl` to modify only the form for ProfileID 42).
+
+You might want to modify a template that isn't directly the page you
+load, but added later via Ajax. For instance, perhaps you want to change
+all the tabs beside the Content Summary (Activities, Groups, etc.). The
+easiest way to do this is to install a development oriented plug-in to
+your web browser. If using Mozilla Firefox, the Firebug plug-in is
+indispensable.  Open the Firebug console (or equivalent in your
+browser)  and click the tab. You will see what URL has been loaded for
+the tab (e.g., for the notes tab:
+`http://example.org/civicrm/contact/view/note?reset=1&snippet=1&cid=1`).
+Open it in a new window or new tab of the web browser, and view the
+source. It also contains a comment identifying the template used (`CRM/Contact/Page/View/Note.tpl`).
+
+Keep in mind that when you modify a template, you might have a template
+that doesn't work properly anymore after an upgrade of CiviCRM, because
+the layout has changed or the name of variables assigned to the template
+was modified. In our experience, the easiest is to use a source code
+management system (SCM) to keep track  of the changes you have made.
+Before doing any modification of the template you copied, add it to your
+SCM, and obviously also commit the template after having modified it.
+That way, you can easily generate a patch of your changes, and see how
+to apply them to the latest version of the template.
+
+## Semantically meaningful HTML attributes
+
+To make it as easy as possible for you to style any element in the page
+(e.g. put a yellow background on all the contacts of the subtype
+"members"), or add Ajax (clicking on the status of the activity changes
+it to complete), we strive to have a consistent and coherent schema for
+class names and ids for the generated HTML. This makes it easier to
+isolate the elements you want to alter from a custom style or from
+JavaScript:
+
+-   There is a class `crm-entityName` defining the type of the entity
+    bubbled up as high as possible in the DOM. For instance, each line
+    on a list of activity has `<tr class="crm-activity ...">`
+-   There is an id `crm-entityName_entityID` allowing to find the id
+    of the entity bubbled up. e.g., on a list of contacts, the
+    contact number 42  has a `<tr id="crm-contact_42" ...>`
+-   Each field or column contains a class identifying it, e.g.,
+    `"crm-activity-subject"`
+-   Each field or column that contains a value with a fixed set of
+    possible values (e.g., a Status, a Role, a Contact Type) contains a
+    class identifying it. It doesn't contain the human readable version
+    (that can be changed), but the id or a name that can't be modified
+    by the end-user; such as `class="crm-activity-status-id_42"`.
+    This is on the top of the class identifying the field name, so the
+    complete HTML is `<td class="crm-activity-status
+    crm-activity-status-id_42">Hitchhiked</td>`.
+
+At the time of the writing, some of the templates don't follow these
+conventions. Please update them and submit a bug tracking issue with a
+patch if you need to use a template that isn't yet complying. For more
+information about submitting a bug or issue, read about the CiviCRM
+community.
+
+## Displaying more content and adding Ajax features
+
+If your modifications go further than "simple" modifications of the
+layout, but need to display more content than the one assigned to the
+template by default, or to add Ajax functionality, use the CiviCRM API.
+Please read more information about using the CiviCRM API from Ajax to
+pursue this approach.
+
+In most cases, using the CiviCRM APIs should be simple and only takes a
+few extra lines of modifications.
+
+## Appending jQuery or other code to a template
+
+You can also append jQuery functions, Smarty code, HTML (really
+anything) to any template without having to create a customized copy of
+the entire file. All you need to do is put your "extra stuff" in a new
+file and save it as `template_to_append_to.extra.tpl`.
+
+**EXAMPLE**: You want to add some jQuery to hide a few of the fields in
+the Contact Edit form - Contact.tpl.
+
+1. Configure your Custom Templates directory
+2. Create the directory structure in your custom templates directory (`CRM/Contact/Form`)
+3. Write your jQuery script and save it in a file called `Contact.extra.tpl`
+
+Voila - your jQuery script will be automatically appended to the
+standard Contact.tpl template when that form is loaded.
+
+One heads up … if your file contains Javascript (as it probably will),
+you will need to start your "extra" custom file with the Smarty
+`{literal}` tag and the `<script>` tag. Then use
+`{/literal}{$variable}{literal}` if you need to use any Smarty code or
+variables. Finally, end the file with `</script>{/literal}`.
+
+For customizations where you just need to add a script, this approach is
+preferable to creating a custom copy of the entire template as it should
+minimize the need for review and merge of changes during upgrades.
+
+## Some useful variables and examples
+
+On each page template, you have extra Smarty variables populated by
+CiviCRM.
+
+* `{$config}` Contains a lot of useful information about your
+environment (including the URL, if it's Drupal or Joomla!, etc.)
+* `{$session}` Contains information about the user.
+
+If you want to modify the template only for a logged-in user but leave
+it identical for anonymous users, do the following:
+
+```smarty
+{if $session->get('userID') > 0} Insert your modifications here {/if}
+```
+
+## Modify templates without using jQuery/javascript
+
+You can insert php code directly into smarty templates, using the `{php}`
+tag. Note that this is deprecated as of Smarty 3.
+
+```smarty
+{php}
+//sets the page title
+CRM_Utils_System::setTitle('Thank You', 'Thank You');
+
+//gets the variable 'form' from smarty and puts it in your php scope so you can play with it
+$form = $this->get_template_vars('form');
+
+//assigns $form back to smarty so you can use it in your template file, outside the {php} scope
+$this->assign('form',$form); 
+{/php}
+```
+
+You can also do various modifications on elements on the page using
+smarty-native or Civi-specific functions:
+
+```smarty
+{* Prefill the input element with the user's email and assign the whole thing to $fieldWithValue. *}
+{assign var="fieldWithValue" value=$form.email_confirm.html|crmInsert:value:$email}
+
+{* Make the field wider *}
+{$fieldWithValue|crmInsert:size:40}
+
+{* Put the result of the include in $modifiedButtons instead of rendering it *}
+{include file="CRM/common/formButtons.tpl" location="bottom" assign="modifiedButtons"}
+
+{* Now change the text of one of the buttons from 'Opt Out' to 'Unsubscribe' *}
+{$modifiedButtons|replace:'value="Opt Out"':'value="Unsubscribe"'}
+```
+
+You can find more such functions in the smarty documentation. And you
+can find other useful Civi-specific functions
+[here](https://github.com/civicrm/civicrm-core/tree/4.6/CRM/Core/Smarty/plugins).
+
+One additional tool you can use is the Word Replacements tool in Civi's
+backend. It's available under **Administer > Customize Data and Screens > Word Replacements**.
diff --git a/docs/security/permissions.md b/docs/security/permissions.md
index 5d16857c79c7ba3e7a0caec5199ecffd786c4b61..884eecef9d2f3f78080b2880fca48db079a114d6 100644
--- a/docs/security/permissions.md
+++ b/docs/security/permissions.md
@@ -1,6 +1,6 @@
 # Permissions Framework in CiviCRM
 
-## Introcution
+## Introduction
 
 CiviCRM has a number of permissions that are able to be set through the relevant permissions page of your Content Management System. These are the primary way CiviCRM controls what parts of the application users are able to see. For example, accessing the "Scheduled Reminders" screen in CiviCRM requires the permission of `Administer CiviCRM` at least. Permissions are also there to control access to various entities such as contacts. There are generally 2 permissions `Access All Contacts` and `Edit All Contacts`. Users which have those permissions will be able to see and possibly edit all contacts.
 
@@ -27,10 +27,20 @@ When you write code, you can look at `CRM_Core_Permission::check` to see if the
 
 Depending on how the API is called, it is either called with a `check_permissions` flag turned off or turned on. When it is turned off, it will run the API without checking if the user has the necessary permissions to perform the action needed. If you turn `check_permissions` on then there will be tests done. By default code in CLI tools e.g. drush or WP-cli or within core code or extension code that is done at run time, the default in CiviCRM APIv3 is that the `check_permissions` flag is turned off. If you call the CiviCRM API through the rest interface then by default the `check_permissions` flag will be turned on. The permissions needed to make various API calls are defined in `CRM_Core_Permission::getEntityActionPermissions()`
 
-## Extending Permissions
+## Extending and Implementing Permission Structure {:#extensions}
+
+In an extension, authors have a wide ability to implement the same permissions structure as in CiviCRM Core but also to extend in a number of ways.
+
+### Implementing Permissions in extensions
+
+[hook_civicrm_navigationMenu](/hooks/hook_civicrm_navigationMenu.md) allows for extension providers to define new menu items and the associated permissions to that menu item. However this does not specifically grant access to the end point just decides whether the menu item or not is visible to the user based on the permissions of that user.
+
+To implement access to a specific url that you are creating as part of your extension. Extension authors should create a `MyExtension.xml` file in `MyExtension/xml/Menu/`. This file should be structure like the core menu XML files and this will determine the permissions to actually access the page not just whether a user can see the menu item or not.
+
+### Extending Permissions
 
 If you want to add a permission to the list in the CMS, you can implement [hook_civicrm_permission](/hooks/hook_civicrm_permission.md). Here, you can specify new permissions that will then be available to select within the CMS permissions.
 
-## Altering API Permissions
+### Altering API Permissions
 
 If you want to alter the permissions the API uses during its permissions check, you can implement the [hook_civicrm_alterAPIPermissions](/hooks/hook_civicrm_alterAPIPermissions.md). Note that you should be very careful when altering any permissions because they may have unintended consequences.
diff --git a/mkdocs.yml b/mkdocs.yml
index 550455e22383a5d9f5b612f4694487457a2841c3..f337758ff4f9875f4337fac47f9d25a1c407cfa3 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -85,6 +85,10 @@ pages:
   - QuickForm Reference:
      - QuickForm: framework/quickform/index.md
      - Entity Reference Field: framework/quickform/entityref.md
+  - Template Reference:
+    - Templates: framework/templates/index.md
+    - Customizing templates: framework/templates/customizing.md
+    - Extending Smarty: framework/templates/extending-smarty.md
   - PseudoConstant Reference: framework/pseudoconstant.md
   # Other Reference:
   - CiviMail: framework/civimail.md
diff --git a/redirects/wiki-crmdoc.txt b/redirects/wiki-crmdoc.txt
index aaabd5a6c97b615368b3658ea34109bd3f03a820..fa25007182e2935cfda2ed718f35b7c980cd9608 100644
--- a/redirects/wiki-crmdoc.txt
+++ b/redirects/wiki-crmdoc.txt
@@ -176,4 +176,8 @@ Contributing+to+CiviCRM+using+GitHub tools/git/#github
 Git+Commit+Messages+for+CiviCRM tools/git/#committing
 Transaction+Reference framework/database/transactions.md
 Backbone+Reference framework/backbone
-CiviMail+Reference framework/civimail
+Extensions+and+Permissions security/permissions#extensions
+Customize+Built-in+Profile+Contribution+and+Event+Registration+Screens framework/templates/customizing
+Page+Templates framework/templates
+Extending+Smarty framework/templates/extending-smarty
+CiviMail+Reference framework/civimail
\ No newline at end of file