Merge remote-tracking branch 'upstream/dev' into dev

Author: mfranzke

packages/docs/src/docs/installation.md

@@ -42,7 +42,7 @@ This will bring up an installation menu that presents the following steps:
 
 ## Step 5: Choose initial patterns
 
-**`What initial patterns do you want included in your project?`** - Choose the <a href="/docs/starterkits/">Starterkit</a> you want to begin your project with. The options are:
+**`What initial patterns do you want included in your project?`** - Choose the [Starterkit](/docs/starterkits/) you want to begin your project with. The options are:
 
 - **`Handlebars base patterns`** `(some basic patterns to get started with)`
 - **`Handlebars demo patterns`** `(full demo website and patterns)`

packages/docs/src/docs/pattern-including.md

@@ -30,7 +30,7 @@ The shorthand include syntax would be:
 
     atoms-landscape-16x9
 
-The pattern type matches the top-level folder and is `atoms`. The pattern name matches the template file and is `landscape-16x9`. Any digits used for ordering are _dropped_ from both the pattern type and pattern name. Pattern subgroups are _never_ a part of the shorthand include syntax. This way patterns can be re-organized within a pattern type and/or by using digits without needing to change your pattern includes.
+The pattern type matches the top-level folder and is `atoms`. The pattern name matches the template file and is `landscape-16x9`. Any digits used in the filename for ordering (which is deprecated, use [the order parameter](/docs/reorganizing-patterns/) instead) are _dropped_ from both the pattern type and pattern name references. Pattern subgroups are _never_ a part of the shorthand include syntax. This way patterns can be re-organized within a pattern type and/or by using digits (which is deprecated, use [the order parameter](/docs/reorganizing-patterns/) instead) without needing to change your pattern includes.
 
 The following are examples of using the shorthand include syntax with our supported PatternEngines:
 
@@ -60,7 +60,7 @@ The default Mustache include syntax would be:
 {% raw %}{{> atoms/images/landscape-16x9 }}{% endraw %}
 ```
 
-**Important:** Unlike the shorthand include syntax the template language specific include syntax **must** include any digits used for ordering and subgroup directories. Pattern paths need to be updated when either is changed for a given pattern.
+**Important:** Unlike the shorthand include syntax the template language specific include syntax **must** include any digits used for ordering (which is deprecated, use [the order parameter](/docs/reorganizing-patterns/) instead) and subgroup directories. Pattern paths need to be updated when either is changed for a given pattern.
 
 ## Examples and Gotchas
 
@@ -69,17 +69,12 @@ Here are some examples of how to include patterns as well as some gotchas.
 ```handlebars
 {% raw %}// partials to match
 atoms/global/test.mustache
-atoms/global/test.mustache
-atoms/global/test.mustache
 atoms/global/test-with-picture.mustache
 
 // using the shorthand partials syntax
 {{> atoms-test }}               // will match atoms/global/test.mustache
-                                // using the shorthand syntax you'll never be able to match test nor test in this scenario
 {{> atoms-test-with-picture }}  // will match atoms/global/test-with-picture.mustache
-{{> atoms-test-wit }}           // will match atoms/global/test-with-picture.mustache
 
 // using the default mustache partials syntax
-{{> atoms/global/test }}     // won't match anything because atoms is missing its digits
 {{> atoms/global/test }}  // will match atoms/global/test.mustache{% endraw %}
 ```