docs: reorganise supported hardware page (#3363)

* docs: supported hardware structure changes

Added a few links to hardware intergration pages to provide clearly signal to reader "you can make your own".
Removed "Contributing" section since it's not really relavent anymore.

* docs: move unsupported boards section out of metadata

* address review comments

* fix broken link

* board variants, interconnect, fix link, move unsupported section

* Apply suggested change

Co-authored-by: Nicolas Munnich <98408764+nmunnich@users.noreply.github.com>

---------

Co-authored-by: Nicolas Munnich <98408764+nmunnich@users.noreply.github.com>

app/boards/interconnects/arduino_uno/arduino_uno.zmk.yml

@@ -9,10 +9,6 @@ description: |
   natural extension, once there were many shields designed for it, many other *boards* began to be developed
   that were compatible to leverage the extensive available shields. Today, many dev kits come with Uno
   headers to make it easy to work with them.
-
-  Note: ZMK doesn't support boards with AVR 8-bit processors, such as the ATmega32U4, because Zephyr™ only
-  supports 32-bit and 64-bit platforms. As a result, boards like the original Arduino Uno Rev3 itself are
-  *not* supported by ZMK.
 node_labels:
   gpio: arduino_header
   i2c: arduino_i2c

app/boards/interconnects/pro_micro/pro_micro.zmk.yml

@@ -6,12 +6,8 @@ url: https://www.sparkfun.com/products/12640
 manufacturer: SparkFun
 description: |
   The SparkFun Pro Micro grew popular as a low cost ATmega32U4 board with sufficient GPIO and peripherals
-  to work for many keyboard needs. Since the original Pro Micro, many pin compatible boards have appeared,
+  to work for many keyboard needs. Since the original Pro Micro, many pin compatible boards have appeared
-  with various changes or improvements, such as the Elite-C w/ USB-C, nice!nano with nRF52840 wireless.
+  with various changes or improvements.
-
-  Note: ZMK doesn't support boards with AVR 8-bit processors, such as the ATmega32U4, because Zephyr™ only
-  supports 32-bit and 64-bit platforms. As a result, controllers like the SparkFun Pro Micro and the Elite-C
-  are *not* supported by ZMK.
 node_labels:
   gpio: pro_micro
   i2c: pro_micro_i2c

docs/docs/hardware.mdx

@@ -11,11 +11,6 @@ import Heading from "@theme/Heading";
 import { groupedMetadata } from "@site/src/components/hardware-utils";
 
 export const toc = [
-  {
-    value: "Onboard Controller Keyboards",
-    id: "onboard",
-    level: 2,
-  },
   {
     value: "Composite Keyboards",
     id: "composite",
@@ -28,25 +23,33 @@ export const toc = [
       id: interconnect.id,
       level: 3,
     })),
+  {
+    value: "Onboard Controller Keyboards",
+    id: "onboard",
+    level: 2,
+  },
   {
     value: "Other Hardware",
     id: "other-hardware",
     level: 2,
   },
-  {
-    value: "Contributing",
-    id: "contributing",
-    level: 2,
-  },
 ];
 
-With the solid technical foundation of Zephyr™ RTOS, ZMK can support a wide diversity of hardware targets,
+With the solid technical foundation of Zephyr™ RTOS, ZMK can support a wide variety of hardware targets,
 including but not limited to Nordic nRF52, Raspberry Pi RP2040/RP2350, most ST STM32 MCUs, and Microchip SAMD21.
-That being said, there are specific [boards / shields](hardware-integration/index.mdx#boards--shields) that have been implemented and tested by the ZMK contributors, listed below.
+ZMK has the potential to run on any hardware supported by Zephyr™, such as those on
+the [Zephyr™ supported boards](https://docs.zephyrproject.org/4.1.0/boards/index.html) page, though you may need to do some additional work to configure them for ZMK.
+That being said, there are specific boards that have been tested and pre-configured by the ZMK contributors, denoted by the `zmk` board variants below.
 
-:::note
+Designing a new keyboard? Check out the [Hardware Integration](hardware-integration/index.mdx) section
+for more information on how to configure ZMK to run on your custom hardware.
 
-With the [upgrade to Zephyr 4.1](/blog/2025/12/09/zephyr-4-1#zmk-board-variant), the ZMK project has moved all in-tree boards to use a `zmk` [board variant](https://docs.zephyrproject.org/4.1.0/glossary.html#term-variant), for consistency when distinguishing from stock boards that are actually in upstream Zephyr.
+:::info[Boards, Board Variants, and Shields]
+
+ZMK uses the Zephyr concepts of "boards" and "shields" to refer to different parts of a keyboard build that are then combined during a firmware build.
+Please see the [explainer on boards & shields](hardware-integration/index.mdx#boards--shields) for more details.
+
+Zephyr boards come with minimal configuration. ZMK board variants add the necessary configuration to make the board usable out of the box with ZMK.
 
 :::
 
@@ -58,7 +61,6 @@ With the [upgrade to Zephyr 4.1](/blog/2025/12/09/zephyr-4-1#zmk-board-variant),
 In addition to the basic keyboard functionality, there is also support for additional keyboard hardware such as encoders, RGB underglow, backlight and displays.
 Please see pages under the "Features" header in the sidebar for details.
 
-{/* prettier-ignore */}
+ZMK doesn't support boards with AVR 8-bit processors, such as the ATmega32U4, because Zephyr™ only
-<Heading as="h2" id="contributing">Contributing</Heading>
+supports 32-bit and 64-bit platforms. As a result, controllers like the SparkFun Pro Micro, Elite-C,
-
+and Arduino Uno Rev3 are **NOT** supported by ZMK.
-If you'd like to add support for a new keyboard shield, head over to the [New Keyboard Shield](hardware-integration/new-shield.mdx) documentation and note the [clean room design requirements](development/contributing/clean-room.md).

docs/src/components/hardware-list.tsx

@@ -84,6 +84,34 @@ function HardwareList({ items }: HardwareListProps) {
 
   return (
     <>
+      <section>
+        <Heading as="h2" id="composite">
+          Composite Keyboards
+        </Heading>
+        <p>
+          Composite keyboards are composed of two main PCBs: a small controller{" "}
+          <strong>board</strong> with exposed pads, and a larger keyboard PCB (a{" "}
+          <strong>shield</strong>, in ZMK lingo) with switch footprints. The
+          board and shield share the same <strong>interconnect</strong>{" "}
+          standard, which defines the physical and electrical specifications for
+          the PCB-to-PCB connection.
+        </p>
+        <p>
+          Boards and shields that share the same interconnect are usually
+          compatible with each other but not always. Check hardware
+          compatibility before connecting them.
+        </p>
+        <p>
+          Designing a custom composite keyboard with an off-the-shelf controller
+          board? Check out the{" "}
+          <a href="/docs/hardware-integration/new-shield">
+            New Keyboard Shield
+          </a>{" "}
+          guide.
+        </p>
+
+        {Object.values(grouped.interconnects).map(mapInterconnect)}
+      </section>
       <section>
         <Heading as="h2" id="onboard">
           Onboard Controller Keyboards
@@ -93,6 +121,10 @@ function HardwareList({ items }: HardwareListProps) {
           the components of a keyboard, including the controller chip, switch
           footprints, etc.
         </p>
+        <p>
+          Designing a custom keyboard with an onboard controller? Check out the{" "}
+          <a href="/docs/hardware-integration/new-board">New Board</a> guide.
+        </p>
         <ul>
           {grouped["onboard"]
             .sort((a, b) => a.name.localeCompare(b.name))
@@ -101,19 +133,6 @@ function HardwareList({ items }: HardwareListProps) {
             ))}
         </ul>
       </section>
-      <section>
-        <Heading as="h2" id="composite">
-          Composite Keyboards
-        </Heading>
-        <p>
-          Composite keyboards are composed of two main PCBs: a small controller
-          board with exposed pads, and a larger keyboard PCB (a shield, in ZMK
-          lingo) with switch footprints and a location where the controller is
-          added. This location is called an interconnect. Multiple interconnects
-          can be found below.
-        </p>
-        {Object.values(grouped.interconnects).map(mapInterconnect)}
-      </section>
     </>
   );
 }