docs: documenting new convention for physical layouts

2 files changed, 25 insertions, 24 deletions

diff --git a/docs/docs/development/hardware-integration/new-shield.mdx b/docs/docs/development/hardware-integration/new-shield.mdx
index 2f4cd05c04..296dbf5986 100644
--- a/docs/docs/development/hardware-integration/new-shield.mdx
+++ b/docs/docs/development/hardware-integration/new-shield.mdx
@@ -448,19 +448,10 @@ Also see the [matrix transform section](../../config/layout.md#matrix-transform)
 
 Your keyboard will need to have a physical layout defined.
 Read through our [dedicated page on physical layouts](./physical-layouts.md) for information on how to define a physical layout.
-Physical layouts should be placed in the same file as the matrix transform, i.e. `my_keyboard.overlay` for unibodies and `my_keyboard.dtsi` for split keyboards.
-
-A very basic physical layout looks like this:
+Once you have finished creating your physical layout, you should import the file in which it was created:
 
 ```dts
-/ {
-    default_layout: default_layout {
-        compatible = "zmk,physical-layout";
-        display-name = "Default Layout";
-        transform = <&default_transform>;
-        kscan = <&kscan0>;
-    };
-};
+#include "my_keyboard-layouts.dtsi"
 ```
 
 ### Chosen Node
@@ -470,7 +461,7 @@ Set the `chosen` node to a defined "default" physical layout. This should also b
 ```dts
 / {
     chosen {
-        zmk,physical-layout = &default_layout;
+        zmk,physical-layout = &physical_layout0;
         // Other chosen items
     };
 };
@@ -485,7 +476,7 @@ If all of your physical layouts use the same `kscan` node under the hood, you ca
 / {
     chosen {
         zmk,kscan = &kscan0;
-        zmk,physical-layout = &default_layout;
+        zmk,physical-layout = &physical_layout0;
         // Other chosen items
     };
 };
diff --git a/docs/docs/development/hardware-integration/physical-layouts.md b/docs/docs/development/hardware-integration/physical-layouts.md
index 7e36574c83..8f3c20ddc8 100644
--- a/docs/docs/development/hardware-integration/physical-layouts.md
+++ b/docs/docs/development/hardware-integration/physical-layouts.md
@@ -10,22 +10,32 @@ It contains:
 - A [matrix transform](../../config/layout.md#matrix-transform)
 - (Optional) [Physical key positions](#optional-keys-property)
 
+By convention, physical layouts and any [position maps](#position-map) are defined in a separate file called `<your keyboard>-layouts.dtsi`.
+This file should then be imported by the appropriate file, such as an `.overlay`, `.dts`, or a `.dtsi` (the last of which is itself imported by one of the previous).
+
 ## Basic Physical Layout
 
-A basic physical layout without the `keys` property looks like this:
+A bare physical layout without the `keys` property looks like this:
 
-```dts
+```dts title="<your keyboard>-layouts.dtsi"
 / {
-    default_layout: default_layout {
+    physical_layout0: physical_layout_0 {
         compatible = "zmk,physical-layout";
         display-name = "Default Layout";
-        transform = <&default_transform>;
-        kscan = <&kscan0>;
     };
 };
 ```
 
-It is given a name, a matrix transform, and a kscan. If all of your physical layouts share the same kscan, then the `kscan` property can be omitted - in this case it needs to be set in the [`chosen` node](./new-shield.mdx#chosen-node). See the [configuration section on physical layouts](../../config/index.md) for reference.
+Every physical layout needs a matrix transform, and optionally can also have a kscan. By convention, these are assigned to the physical layout in the file where the matrix transform and kscan are defined:
+
+```dts title="<your keyboard>.dts | <your keyboard>.dtsi | <your keyboard>.overlay"
+&physical_layout0 {
+    kscan = <&kscan0>;
+    transform = <&matrix_transform0>;
+};
+```
+
+The `kscan` property only needs to be assigned if some of your physical layouts use different kscans. Otherwise, it can be omitted and the `kscan` can be assigned in the [`chosen` node](./new-shield.mdx#chosen-node) instead. See the [configuration section on physical layouts](../../config/layout.md#physical-layout) for reference.
 
 ## (Optional) Keys Property
 
@@ -35,11 +45,11 @@ ZMK Studio is in beta. Although every effort has been made to provide a stable e
 
 :::
 
-The `keys` property is required for [ZMK Studio](../../features/studio.md) support. It is used to describe the physical attributes of each key position present in that layout. If this property is used, then you should define the physical layouts and any [position maps](#position-map) in a file called `<your keyboard>-layouts.dtsi`. This file should then be imported by the appropriate file, such as an `.overlay`, `.dts`, or a `.dtsi` (last of which is itself imported by one of the previous).
+The `keys` property is required for [ZMK Studio](../../features/studio.md) support. It is used to describe the physical attributes of each key position present in that layout.
 
 To pull in the necessary definition for creating physical layouts with the `keys` property, a new include should be added to the top of the devicetree file:
 
-```
+```dts title="<your keyboard>-layouts.dtsi"
 #include <physical_layouts.dtsi>
 ```
 
@@ -64,7 +74,7 @@ You can specify negative values in devicetree using parentheses around it, e.g.
 
 Here is an example of a physical layout for a 2x2 macropad:
 
-```dts
+```dts title="macropad-layouts.dtsi"
 #include <physical_layouts.dtsi>
 
 / {
@@ -90,7 +100,7 @@ To use such layouts, import them and assign their `transform` and (optionally) `
 
 Here is an example of using the predefined physical layouts for a keyboard with the same layout as the "ferris":
 
-```dts
+```dts title="ferris.dtsi"
 #include <layouts/cuddlykeyboards/ferris.dtsi>
 
 // Assigning suitable kscan and matrix transforms
@@ -104,7 +114,7 @@ Shared physical layouts found in the same folder are defined such that they can
 
 Here is an example of using the predefined physical layouts for a 60% keyboard:
 
-```dts
+```dts title="bt60_v1.dts"
 #include <layouts/common/60percent/all1u.dtsi>
 #include <layouts/common/60percent/ansi.dtsi>
 #include <layouts/common/60percent/hhkb.dtsi>