Merge pull request #1138 from ExpressionEngine/7.dev

Pushing live config file route docs

Author: TomJaeger

docs/config/config-files.md

@@ -68,7 +68,12 @@ This file holds the duration of user session when 'remember me' checkbox is chec
 
 This file lets you re-map URI requests to specific controller functions.
 
-We generally recommend using [Template Routes](templates/routes.md) and not modify this file, unless you know you need to.
+This is different from Template Routes for templates.
+
+- Controller routes (`routes.php`) map requests to controller methods.
+- Template Routes map requests to templates and are documented in [Template Routes](templates/routes.md).
+
+If you want to define Template Routes in config, use `$config['routes']` (or `$config['routes:<site_id>']`) in `system/user/config/config.php` and keep [`enable_template_routes`](general/system-configuration-overrides.md#enable_template_routes) enabled.
 
 #### Stop Words
 

docs/general/system-configuration-overrides.md

@@ -1393,6 +1393,8 @@ Example Usage:
 
 This setting toggles whether or not Template Routes are used. If this is set to no, templates will not be accessible by their routes. When disabled the Template Route options will not appear in the Template Manager.
 
+This setting applies to both Template Routes managed in the Control Panel and config-defined routes in `$config['routes']` / `$config['routes:<site_id>']`. If this is `n`, route matching is disabled.
+
 | Value | Behavior                         |
 | ----- | -------------------------------- |
 | y     | Enable Template Routes (default) |
@@ -1402,6 +1404,8 @@ Example Usage:
 
     $config['enable_template_routes'] = 'y';
 
+For config-defined route mappings, see [Template Routes](templates/routes.md#config-defined-routes).
+
 ## `enable_throttling`
 
 If enabled, the system will throttle excessive web requests from potentially malicious users.

docs/templates/routes.md

@@ -39,6 +39,47 @@ An issue arises if ExpressionEngine parses your routes in the above order when t
 
 NOTE: **Important:** Template Routes overrides the default behavior of URLs, if you wish to use a Channel Entries Tag in your template you must manually provide segments for any parameters that are normally set in the URL. You must provide a segment for pagination, categories, and entry titles if you wish to use those in your Channel Entries Tag. Additionally, be careful when using `dynamic="yes"` with Template Routes, this can cause issues if your route does not have an appropriate segment set.
 
+## Config-Defined Routes
+
+In addition to managing routes in the Control Panel, you can define Template Routes directly in `system/user/config/config.php`.
+
+Template Route matching requires [`enable_template_routes`](general/system-configuration-overrides.md#enable_template_routes) to be enabled. This setting defaults to `y`, so you only need to set it if it was previously disabled.
+
+    $config['enable_template_routes'] = 'y';
+
+Define routes as an associative array where:
+
+- the key is `template_group/template_name`
+- the value is the route pattern string
+
+Example:
+
+    $config['routes'] = [
+        'blog/index' => '/blarg',
+        'blog/entry' => '/blarg/{url_title}',
+    ];
+
+Regex rules use the same syntax as any other Template Route rule:
+
+    $config['routes'] = [
+        'blog/article' => '/news/{slug:regex[([a-z0-9-]+)]}',
+        'blog/year'    => '/archive/{year:regex[((19|20)\d{2})]}',
+    ];
+
+These routes use the same rule engine as routes created in the Template Manager.
+
+NOTE: **Note:** When `$config['routes']` is present, the Template Route Manager is not available in the Control Panel. Manage those routes in config as the source of truth.
+
+NOTE: **Advanced (MSM):** For site-specific route definitions, use `$config['routes:<site_id>']`. ExpressionEngine checks this key first and falls back to `$config['routes']` if no site-specific routes are defined.
+
+    $config['routes:1'] = [
+        'blog/index' => '/site-one-blog',
+    ];
+
+    $config['routes'] = [
+        'blog/index' => '/blog',
+    ];
+
 ### Template Route
 
 This route determines the URLs that will match your template. The format is as follows: