docs: Move the hardware integration section out of development (#3360)

app/keymap-module/modules/modules.cmake

@@ -50,12 +50,12 @@ if (ZMK_CONFIG)
     set(ENV{ZMK_CONFIG} "${ZMK_CONFIG}")
     if(EXISTS ${ZMK_CONFIG}/boards)
         message(STATUS "Adding ZMK config directory as board root: ${ZMK_CONFIG}")
-        message(DEPRECATION "The `config/boards` folder is deprecated. Please use a module instead. See https://zmk.dev/docs/development/hardware-integration/new-shield and https://zmk.dev/docs/development/module-creation for more information.")
+        message(DEPRECATION "The `config/boards` folder is deprecated. Please use a module instead. See https://zmk.dev/docs/hardware-integration/new-shield and https://zmk.dev/docs/development/module-creation for more information.")
         list(APPEND BOARD_ROOT ${ZMK_CONFIG})
     endif()
     if(EXISTS ${ZMK_CONFIG}/dts)
         message(STATUS "Adding ZMK config directory as DTS root: ${ZMK_CONFIG}")
-        message(DEPRECATION "The `config/dts` folder is deprecated. Please use a module instead. See https://zmk.dev/docs/development/hardware-integration/new-shield and https://zmk.dev/docs/development/module-creation for more information.")
+        message(DEPRECATION "The `config/dts` folder is deprecated. Please use a module instead. See https://zmk.dev/docs/hardware-integration/new-shield and https://zmk.dev/docs/development/module-creation for more information.")
         list(APPEND DTS_ROOT ${ZMK_CONFIG})
     endif()
 endif()

app/src/physical_layouts.c

@@ -71,7 +71,7 @@ BUILD_ASSERT(
 #define ZMK_LAYOUT_INST(n)                                                                         \
     BUILD_ASSERT(!IS_ENABLED(CONFIG_ZMK_STUDIO) || DT_INST_NODE_HAS_PROP(n, keys),                 \
                  "ZMK Studio requires physical layouts with key positions. See "                   \
-                 "https://zmk.dev/docs/development/hardware-integration/studio-setup");            \
+                 "https://zmk.dev/docs/hardware-integration/studio-setup");                        \
     static const struct zmk_key_physical_attrs _CONCAT(_zmk_physical_layout_keys_,                 \
                                                        n)[DT_INST_PROP_LEN_OR(n, keys, 0)] = {     \
         LISTIFY(DT_INST_PROP_LEN_OR(n, keys, 0), ZKPA_INIT, (, ), n)};                             \

app/src/split/wired/central.c

@@ -77,7 +77,7 @@ static const struct gpio_dt_spec detect_gpio = GPIO_DT_SPEC_INST_GET(0, detect_g
 #else
 
 #error                                                                                             \
-    "Need to create a node with compatible of 'zmk,wired-split` with a `device` property set to an enabled UART. See http://zmk.dev/docs/development/hardware-integration/new-shield#wired-split"
+    "Need to create a node with compatible of 'zmk,wired-split` with a `device` property set to an enabled UART. See http://zmk.dev/docs/hardware-integration/new-shield#wired-split"
 
 #endif
 

app/src/split/wired/peripheral.c

@@ -76,7 +76,7 @@ static const struct gpio_dt_spec detect_gpio = GPIO_DT_SPEC_INST_GET(0, detect_g
 #else
 
 #error                                                                                             \
-    "Need to create a node with compatible of 'zmk,wired-split` with a `device` property set to an enabled UART. See http://zmk.dev/docs/development/hardware-integration/new-shield#wired-split"
+    "Need to create a node with compatible of 'zmk,wired-split` with a `device` property set to an enabled UART. See http://zmk.dev/docs/hardware-integration/new-shield#wired-split"
 
 #endif
 

docs/blog/2020-08-12-zmk-sotf-1.md

@@ -18,7 +18,7 @@ There's been lots of various activity in ZMK land!
 - Tons of [documentation](/docs) work.
 - Refactoring ([#73](https://github.com/zmkfirmware/zmk/pull/73), [#74](https://github.com/zmkfirmware/zmk/pull/74)) of [keymaps](/docs/keymaps) to make them simpler for users.
 - Mod-Tap Behavior (docs coming!) is much improved ([#69](https://github.com/zmkfirmware/zmk/pull/69)) and usable now.
-- An initial [`setup.sh`](/docs/user-setup#user-config-setup-script) script was created, allowing users to quickly bootstrap a "user config" setup and push it to GitHub, where GitHub Actions will build the firmware for you.
+- An initial `setup.sh` script was created, allowing users to quickly bootstrap a "user config" setup and push it to GitHub, where GitHub Actions will build the firmware for you.
 - Corne shield ([#80](https://github.com/zmkfirmware/zmk/pull/80)) shield definition was added.
 - Initial [encoder](/docs/features/encoders) support ([#61](https://github.com/zmkfirmware/zmk/pull/61)) was added.
 

docs/blog/2022-04-10-zmk-sotf-5.md

@@ -219,7 +219,7 @@ This can be useful to be sure that lowering brightness doesn't set the brightnes
 
 ## Board/Shield Metadata
 
-[nicell] and [petejohanson] worked together in [#883](https://github.com/zmkfirmware/zmk/pull/883) to settle on a [metadata format](/docs/development/hardware-integration/hardware-metadata-files) that is used to document every board and shield. This now drives automatic generation of our [supported hardware](/docs/hardware) page and our
+[nicell] and [petejohanson] worked together in [#883](https://github.com/zmkfirmware/zmk/pull/883) to settle on a [metadata format](/docs/hardware-integration/hardware-metadata-files) that is used to document every board and shield. This now drives automatic generation of our [supported hardware](/docs/hardware) page and our
 more nuanced GH Actions automation for testing changes to ZMK.
 
 ## Coming Soon!

docs/blog/2023-10-05-zmk-sotf-6.md

@@ -173,7 +173,7 @@ For users or future contributors that might want to dive into writing their own
 
 #### Shield interconnects
 
-[petejohanson] updated the [new shield guide](/docs/development/hardware-integration/new-shield) for non-Pro Micro interconnects including Xiao, Arduino Uno and Blackpill in [#1607](https://github.com/zmkfirmware/zmk/pull/1607).
+[petejohanson] updated the [new shield guide](/docs/hardware-integration/new-shield) for non-Pro Micro interconnects including Xiao, Arduino Uno and Blackpill in [#1607](https://github.com/zmkfirmware/zmk/pull/1607).
 
 #### Bluetooth feature page
 

docs/blog/2024-01-05-zmk-tools.md

@@ -19,7 +19,7 @@ Stay tuned for future installments in the series!
 
 ## ZMK Tools
 
-[ZMK Tools](https://github.com/joelspadin/zmk-tools) is an extension for [Visual Studio Code](https://code.visualstudio.com) that helps with editing a ZMK user config repo or a fork of ZMK. I originally created it to add some code completion in `.keymap` files, but then I realized that with the web version of VS Code, I could also let you set up a user config repo and build firmware, much like the [user setup script](/docs/user-setup#user-config-setup-script), except without downloading a single thing.
+[ZMK Tools](https://github.com/joelspadin/zmk-tools) is an extension for [Visual Studio Code](https://code.visualstudio.com) that helps with editing a ZMK user config repo or a fork of ZMK. I originally created it to add some code completion in `.keymap` files, but then I realized that with the web version of VS Code, I could also let you set up a user config repo and build firmware, much like the user setup script, except without downloading a single thing.
 
 ### User Config Setup in Browser
 

docs/blog/2024-11-11-zmk-studio-mvp-ga.mdx

@@ -225,7 +225,7 @@ return (
 
 :::note
 
-For keyboard maintainers, additional changes are needed to add metadata about the keyboard's physical layouts in order to use ZMK Studio. See the documentation on [physical layouts](/docs/development/hardware-integration/physical-layouts#optional-keys-property) for more information.
+For keyboard maintainers, additional changes are needed to add metadata about the keyboard's physical layouts in order to use ZMK Studio. See the documentation on [physical layouts](/docs/hardware-integration/physical-layouts#optional-keys-property) for more information.
 :::
 
 To use ZMK Studio, you need to have a firmware for your keyboard with the feature enabled, as well as a small keymap change to add an unlock key. See [Building with ZMK Studio](/docs/features/studio#building) and [ZMK Studio keymap changes](/docs/features/studio#keymap-changes) for more details.

docs/blog/2025-12-09-zephyr-4-1.md

@@ -257,7 +257,7 @@ A few other changes, unrelated to the HWMv2 move, may impact out-of-tree boards/
 
 ### Bootloader Setup
 
-With the version bump, the previous method to enable `&bootloader` has been disabled. Instead, ZMK is introducing _boot retention_, which as a side effect also enables `&bootloader` for SoCs which previously didn't work with said behavior, such as the STM32F072. To set up boot retention for your board, please read through [the dedicated page](/docs/development/hardware-integration/bootloader).
+With the version bump, the previous method to enable `&bootloader` has been disabled. Instead, ZMK is introducing _boot retention_, which as a side effect also enables `&bootloader` for SoCs which previously didn't work with said behavior, such as the STM32F072. To set up boot retention for your board, please read through [the dedicated page](/docs/hardware-integration/bootloader).
 
 ### nRF52840 NFC Pins as GPIO
 

docs/docs/config/bootloader.md

@@ -32,7 +32,7 @@ To ensure the BOOT button on keyboard and controllers using these SoCs works as
 
 ### Bootmode Magic Value Mapper
 
-Some target SoCs may use the bootmode magic value mapper for [bootloader integration](docs/development/hardware-integration/bootloader/index.mdx). When doing so, the following configurations are used:
+Some target SoCs may use the bootmode magic value mapper for [bootloader integration](docs/hardware-integration/bootloader/index.mdx). When doing so, the following configurations are used:
 
 | Config                                                           | Type | Description                                                                           | Default |
 | ---------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------- | ------- |

docs/docs/config/index.md

@@ -64,7 +64,7 @@ ZMK will search the shield folder for the following config files _in addition_ t
 
 Shared config files (excluding any `_left` or `_right` suffix) are not currently supported in shield folders.
 
-For more documentation on creating and configuring a new shield, see [Zephyr's shield documentation](https://docs.zephyrproject.org/4.1.0/hardware/porting/shields.html) and [ZMK's new keyboard shield](../development/hardware-integration/new-shield.mdx) guide.
+For more documentation on creating and configuring a new shield, see [Zephyr's shield documentation](https://docs.zephyrproject.org/4.1.0/hardware/porting/shields.html) and [ZMK's new keyboard shield](../hardware-integration/new-shield.mdx) guide.
 
 ## Kconfig Files
 

docs/docs/config/layout.md

@@ -11,7 +11,7 @@ Defines a mapping from keymap logical positions to physical [kscan](./kscan.md)
 
 You can define multiple matrix transform nodes, one for each layout, and users can select which one they want from the `/chosen` node in their keymaps.
 
-See the [new shield guide](../development/hardware-integration/new-shield.mdx#matrix-transform) for more documentation on how to define a matrix transform.
+See the [new shield guide](../hardware-integration/new-shield.mdx#matrix-transform) for more documentation on how to define a matrix transform.
 
 ### Devicetree
 
@@ -174,7 +174,7 @@ Note that the entire addressable space does not need to be mapped.
 
 Defines a keyboard layout by joining together a [matrix transform](#matrix-transform), a [keyboard scan](./kscan.md), and a list of physical key properties.
 Multiple physical layouts can be defined for keyboards with multiple physical key layouts.
-Read through the [page on physical layouts](../development/hardware-integration/physical-layouts.md) for more information.
+Read through the [page on physical layouts](../hardware-integration/physical-layouts.md) for more information.
 
 ### Devicetree
 
@@ -211,7 +211,7 @@ The `key_physical_attrs` node is defined in [`dts/physical_layouts.dtsi`](https:
 
 ## Physical Layout Position Map
 
-Defines a mapping between [physical layouts](#physical-layout), allowing key mappings to be preserved in the same locations as previously when using [ZMK Studio](../features/studio.md). Read through the [page on physical layouts](../development/hardware-integration/physical-layouts.md) for more information.
+Defines a mapping between [physical layouts](#physical-layout), allowing key mappings to be preserved in the same locations as previously when using [ZMK Studio](../features/studio.md). Read through the [page on physical layouts](../hardware-integration/physical-layouts.md) for more information.
 
 ### Devicetree
 

docs/docs/config/lighting.md

@@ -7,7 +7,7 @@ See the [Lighting feature page](../features/lighting.md) for an overview of the
 
 ## RGB Underglow
 
-See the [RGB underglow section](../features/lighting.md#rgb-underglow) in the Lighting feature page for more details, and [hardware integration page](../development/hardware-integration/lighting/underglow.md) for adding underglow support to a board.
+See the [RGB underglow section](../features/lighting.md#rgb-underglow) in the Lighting feature page for more details, and [hardware integration page](../hardware-integration/lighting/underglow.md) for adding underglow support to a board.
 
 See [Configuration Overview](index.md) for instructions on how to change these settings.
 
@@ -52,11 +52,11 @@ The `*_START` settings only determine the initial underglow state. Any changes y
 
 ZMK does not have any Devicetree properties of its own. See the Devicetree bindings for [Zephyr's LED strip drivers](https://github.com/zephyrproject-rtos/zephyr/tree/main/dts/bindings/led_strip).
 
-See the [RGB underglow hardware integration page](../development/hardware-integration/lighting/underglow.md) for examples of the properties that must be set to enable underglow.
+See the [RGB underglow hardware integration page](../hardware-integration/lighting/underglow.md) for examples of the properties that must be set to enable underglow.
 
 ## Backlight
 
-See the [backlight section](../features/lighting.md#backlight) in Lighting feature page for more details, and [hardware integration page](../development/hardware-integration/lighting/backlight.mdx) for adding backlight support to a board.
+See the [backlight section](../features/lighting.md#backlight) in Lighting feature page for more details, and [hardware integration page](../hardware-integration/lighting/backlight.mdx) for adding backlight support to a board.
 
 See [Configuration Overview](index.md) for instructions on how to change these settings.
 
@@ -90,4 +90,4 @@ See the Zephyr devicetree bindings for LED drivers:
 - [gpio-leds](https://docs.zephyrproject.org/4.1.0/build/dts/api/bindings/led/gpio-leds.html)
 - [pwm-leds](https://docs.zephyrproject.org/4.1.0/build/dts/api/bindings/led/pwm-leds.html)
 
-See the [backlight hardware integration page](../development/hardware-integration/lighting/backlight.mdx) for examples of the properties that must be set to enable backlighting.
+See the [backlight hardware integration page](../hardware-integration/lighting/backlight.mdx) for examples of the properties that must be set to enable backlighting.

docs/docs/config/pointing.md

@@ -53,7 +53,7 @@ Additional properties can be set on child nodes, which allows changing the setti
 
 ## Input Split
 
-Input splits are used for [pointing devices on split peripherals](../development/hardware-integration/pointing.mdx#listener-and-input-split-device).
+Input splits are used for [pointing devices on split peripherals](../hardware-integration/pointing.mdx#listener-and-input-split-device).
 
 ### Devicetree
 

docs/docs/config/settings.md

@@ -36,7 +36,7 @@ Definition file: [zmk/app/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/
 
 While regular ZMK builds will not cause any settings to be cleared upon flashing, flashing a build with `CONFIG_ZMK_SETTINGS_RESET_ON_START` enabled as documented above will cause the firmware to run a special procedure when the controller starts that clears the settings partition.
 
-For end users, it is recommended to use a special [shield](../development/hardware-integration/index.mdx#boards--shields) named `settings_reset` to build a new firmware file, then flash that firmware.
+For end users, it is recommended to use a special [shield](../hardware-integration/index.mdx#boards--shields) named `settings_reset` to build a new firmware file, then flash that firmware.
 See example for building firmware using this shield in the [troubleshooting docs](../troubleshooting/connection-issues.mdx#building-a-reset-firmware).
 
 In both cases, regular, non-reset firmware will need to be flashed afterwards for normal operation.

docs/docs/config/split.md

@@ -76,7 +76,7 @@ The following settings only apply when using wired split in polling mode:
 
 ### Wired Split
 
-Wired splits require a properly configured UART to function. If writing a shield, you may be able to use the standard UART already provided by the board, e.g. `&pro_micro_serial`. See [predefined nodes](../development/hardware-integration/pinctrl.mdx#predefined-nodes) for details on the UART node labels provided by various interconnects. If you are creating your own board, or using custom pins for the UART, see the documentation on [pin control](../development/hardware-integration/pinctrl.mdx#additional-examples) to configure the pins for your UART.
+Wired splits require a properly configured UART to function. If writing a shield, you may be able to use the standard UART already provided by the board, e.g. `&pro_micro_serial`. See [predefined nodes](../hardware-integration/pinctrl.mdx#predefined-nodes) for details on the UART node labels provided by various interconnects. If you are creating your own board, or using custom pins for the UART, see the documentation on [pin control](../hardware-integration/pinctrl.mdx#additional-examples) to configure the pins for your UART.
 
 Once you have a properly configured UART device, it needs to be assigned in a new node with a compatible value of `"zmk,wired-split"`. For example:
 

docs/docs/development/local-toolchain/build-flash.mdx

@@ -160,7 +160,7 @@ west build -b nice_nano -- -DSHIELD=vendor_shield -DZMK_EXTRA_MODULES="C:/Users/
 ### Building from `zmk-config` Folder
 
 Instead of building .uf2 files using the default keymap and config files, you
-can build using files from your [`zmk-config` folder](../../user-setup.mdx#github-repo)
+can build using files from your [`zmk-config` folder](../../user-setup.mdx#config-repo-setup)
 by adding `-DZMK_CONFIG="C:/the/absolute/path/config"` to your `west build`
 command. **Notice that this path should point to the folder labeled `config`
 within your `zmk-config` folder.**

docs/docs/faq.md

@@ -51,7 +51,7 @@ ZMK is still in its infancy, so there’s a learning curve involved. But if you
 
 ZMK uses the Zephyr concepts of "boards" and "shields" to refer to different parts of a keyboard build, that in turn get combined during a firmware build.
 This provides the modularity to be able to use composite keyboards with different compatible controllers.
-Please see the [explainer on boards & shields](development/hardware-integration/index.mdx#boards--shields) for more details.
+Please see the [explainer on boards & shields](hardware-integration/index.mdx#boards--shields) for more details.
 
 ### Does ZMK support wired split?
 
@@ -63,7 +63,7 @@ The latency of ZMK is comparable to other firmware offerings. ZMK is equipped wi
 
 ### Any chance for 2.4GHz dongle implementation?
 
-At this time, there are no current plans to implement 2.4GHz dongle mode. This is because utilizing Nordic's proprietary 2.4GHz low level protocols requires use of the Nordic Connect SDK, which is licensed with a more restrictive license than ZMK's MIT license. However, it is possible to [create a dongle](development/hardware-integration/dongle.mdx) for your keyboard that runs ZMK and communicates between parts using BLE (with encryption). This results in a 3.75ms average theoretical latency from the protocol itself.
+At this time, there are no current plans to implement 2.4GHz dongle mode. This is because utilizing Nordic's proprietary 2.4GHz low level protocols requires use of the Nordic Connect SDK, which is licensed with a more restrictive license than ZMK's MIT license. However, it is possible to [create a dongle](hardware-integration/dongle.mdx) for your keyboard that runs ZMK and communicates between parts using BLE (with encryption). This results in a 3.75ms average theoretical latency from the protocol itself.
 
 ### What bootloader does ZMK use?
 

docs/docs/features/battery.md

@@ -16,4 +16,4 @@ Windows may not properly ask the keyboard to notify it of changes in battery lev
 ## Adding a Battery Sensor to a Board
 
 If your keyboard is using one of the [boards supported in ZMK](../hardware.mdx) it will already be configured to sense and report battery levels.
-If you are using a custom board, see [battery sensing hardware integration page](../development/hardware-integration/battery.md) to add support.
+If you are using a custom board, see [battery sensing hardware integration page](../hardware-integration/battery.md) to add support.

docs/docs/features/encoders.md

@@ -41,4 +41,4 @@ Here, the left encoder is configured to control volume up and down while the rig
 
 ## Adding Encoder Support
 
-See the [Hardware Integration page for encoders](../development/hardware-integration/encoders.md) for instructions on adding them to your keyboard.
+See the [Hardware Integration page for encoders](../hardware-integration/encoders.md) for instructions on adding them to your keyboard.

docs/docs/features/led-indicators.md

@@ -58,10 +58,10 @@ For example, if you want the LED to be off when the indicator is active, 100% br
 
 If the LED is not configured to support brightness control, any value greater than 0 will result in maximum brightness.
 
-For most LEDs, you can enable PWM brightness control, though this will increase power usage slightly. See the [LED indicators hardware integration page](../development/hardware-integration/lighting/led-indicators.md) for details on configuring the LEDs.
+For most LEDs, you can enable PWM brightness control, though this will increase power usage slightly. See the [LED indicators hardware integration page](../hardware-integration/lighting/led-indicators.md) for details on configuring the LEDs.
 
 :::
 
 ## Adding LED Indicator Support to a Keyboard
 
-See the [LED indicators hardware integration page](../development/hardware-integration/lighting/led-indicators.md) for instructions to enable this feature on a keyboard.
+See the [LED indicators hardware integration page](../hardware-integration/lighting/led-indicators.md) for instructions to enable this feature on a keyboard.

docs/docs/features/lighting.md

@@ -73,7 +73,7 @@ See [RGB underglow configuration](../config/lighting.md#rgb-underglow).
 
 ### Adding RGB Underglow Support to a Keyboard
 
-See [RGB underglow hardware integration page](../development/hardware-integration/lighting/underglow.md) on adding underglow support to a ZMK keyboard.
+See [RGB underglow hardware integration page](../hardware-integration/lighting/underglow.md) on adding underglow support to a ZMK keyboard.
 
 ## Backlight
 
@@ -100,4 +100,4 @@ See [backlight configuration](../config/lighting.md#backlight) for details.
 
 ### Adding Backlight to a Board or a Shield
 
-See [backlight hardware integration page](../development/hardware-integration/lighting/backlight.mdx) for information on adding backlight support to a ZMK keyboard.
+See [backlight hardware integration page](../hardware-integration/lighting/backlight.mdx) for information on adding backlight support to a ZMK keyboard.

docs/docs/features/low-power-states.md

@@ -78,4 +78,4 @@ You can then wake up the keyboard by pressing the reset button once, and repeati
 
 ### Adding Soft Off to a Keyboard
 
-Please refer to the [corresponding page under hardware integration](../development/hardware-integration/soft-off-setup.mdx) for details.
+Please refer to the [corresponding page under hardware integration](../hardware-integration/soft-off-setup.mdx) for details.

docs/docs/features/pointing.md

@@ -24,7 +24,7 @@ See the [mouse emulation behaviors](../keymaps/behaviors/mouse-emulation.md) for
 
 There are a few drivers available for supporting physical pointing devices integrated into a ZMK powered device. When doing so, you can use your device as both a keyboard and a pointing device with any connected hosts. The functionality can be extended further, e.g. slow mode, scroll mode, temporary mouse layers, etc. by configuring [input processors](#input-processors) linked to the physical pointing device.
 
-For more information, refer to the [pointer hardware integration](../development/hardware-integration/pointing.mdx) documentation.
+For more information, refer to the [pointer hardware integration](../hardware-integration/pointing.mdx) documentation.
 
 ## Input Processors
 

docs/docs/features/split-keyboards.md

@@ -8,7 +8,7 @@ ZMK supports setups where a keyboard is split into two or more physical parts (a
 ## Central and Peripheral Roles
 
 In split keyboards running ZMK, one part is assigned the "central" role which receives key position and sensor events from the other parts that are called "peripherals."
-The central runs the necessary keymap logic to convert received events into HID events such as keycodes and then communicates with the connected host devices, e.g. over USB or bluetooth. If the keyboard makes use of a [dongle](../development/hardware-integration/dongle.mdx), then the dongle takes on the role of central.
+The central runs the necessary keymap logic to convert received events into HID events such as keycodes and then communicates with the connected host devices, e.g. over USB or bluetooth. If the keyboard makes use of a [dongle](../hardware-integration/dongle.mdx), then the dongle takes on the role of central.
 
 The internal keyboard state (like active layers) is handled exclusively by the central.
 Peripherals _cannot_ communicate with host devices on their own, since they can only communicate with the central.
@@ -23,7 +23,7 @@ You can refer to the [power profiler](/power-profiler) to see battery life estim
 
 ### Configuration
 
-The [new shield guide](../development/hardware-integration/new-shield.mdx) details how to define a split keyboard shield with two parts, enabling the split feature and setting up the necessary roles for each part.
+The [new shield guide](../hardware-integration/new-shield.mdx) details how to define a split keyboard shield with two parts, enabling the split feature and setting up the necessary roles for each part.
 
 Also see the reference section on [split keyboards configuration](../config/split.md) where the relevant symbols include `CONFIG_ZMK_SPLIT` that enables the feature, `CONFIG_ZMK_SPLIT_ROLE_CENTRAL` which sets the central role and `CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS` that sets the number of peripherals.
 
@@ -44,7 +44,7 @@ Many popular cables, in particular, TRRS/TRS cables, can cause irreparable damag
 
 ### Bluetooth
 
-[Bluetooth](./bluetooth.md) is the most well tested and flexible transport available in ZMK. Using Bluetooth, a central can connect to multiple peripherals, enabling the use of a [dongle](../development/hardware-integration/dongle.mdx) to improve battery life, or allowing for multi-part split keyboards.
+[Bluetooth](./bluetooth.md) is the most well tested and flexible transport available in ZMK. Using Bluetooth, a central can connect to multiple peripherals, enabling the use of a [dongle](../hardware-integration/dongle.mdx) to improve battery life, or allowing for multi-part split keyboards.
 
 This transport will be enabled for designs that set `CONFIG_ZMK_SPLIT=y` and have `CONFIG_ZMK_BLE=y` set by a supported MCU/controller.
 

docs/docs/features/studio.md

@@ -172,12 +172,12 @@ The reserved layers will be ignored during regular ZMK builds but will become av
 
 To allow ZMK Studio to be used with a keyboard, the keyboard will need to have a physical layout with the `keys` property defined. The keyboard should also **not** have a `chosen` `zmk,matrix-transform`. Relevant information can be found in:
 
-- The [dedicated page on physical layouts](../development/hardware-integration/physical-layouts.md), informing you how to define one
+- The [dedicated page on physical layouts](../hardware-integration/physical-layouts.md), informing you how to define one
-- The [new shield guide](../development/hardware-integration/new-shield.mdx), informing you how to select a physical layout once defined
+- The [new shield guide](../hardware-integration/new-shield.mdx), informing you how to select a physical layout once defined
 - The corresponding [configuration page](../config/layout.md#physical-layout), for reference
 
 To use the `studio-rpc-usb-uart` snippet, the keyboard also needs to be configured to allow CDC-ACM console snippets (this is also used for [USB logging](../development/usb-logging.mdx)). If your keyboard is a composite keyboard, consisting of an in-tree board and a shield, then you can skip this step as the board will already be configured properly. Relevant information on that can be found [in the Zephyr documentation](https://docs.zephyrproject.org/4.1.0/snippets/cdc-acm-console/README.html).
 
 Firmware with ZMK Studio enabled require significantly more RAM. Some MCUs, such as the STM32F072 series, will require fine tuning of various settings in order to reduce the RAM consumption enough for a Studio enabled build to fit.
 
-Finally, once you have successfully built and tested firmware with ZMK Studio enabled, add the `studio` flag to your keyboard's [metadata](../development/hardware-integration/hardware-metadata-files#features).
+Finally, once you have successfully built and tested firmware with ZMK Studio enabled, add the `studio` flag to your keyboard's [metadata](../hardware-integration/hardware-metadata-files#features).

docs/docs/hardware-integration/battery.md

@@ -3,7 +3,7 @@ title: Battery Sensing
 sidebar_label: Battery Sensing
 ---
 
-If your keyboard is using one of the [boards supported in ZMK](../../hardware.mdx) it will already be configured to [sense and report battery levels](../../features/battery.md).
+If your keyboard is using one of the [boards supported in ZMK](../hardware.mdx) it will already be configured to [sense and report battery levels](../features/battery.md).
 Below instructions are only intended for users defining and using a custom board.
 
 To enable a battery sensor on a new board, add the driver for the sensor to your board's `.dts` file. ZMK provides two drivers for estimating the battery level using its voltage:
@@ -11,7 +11,7 @@ To enable a battery sensor on a new board, add the driver for the sensor to your
 - `zmk,battery-voltage-divider`: Reads the voltage on an analog input pin.
 - `zmk,battery-nrf-vddh`: Reads the power supply voltage on a Nordic nRF52's VDDH pin.
 
-See the [battery level configuration page](../../config/battery.md) for the configuration supported by each driver provided by ZMK.
+See the [battery level configuration page](../config/battery.md) for the configuration supported by each driver provided by ZMK.
 
 Zephyr also provides some drivers for fuel gauge ICs such as the TI bq274xx series and Maxim MAX17xxx series. If you use a battery sensor that does not have an existing driver, you will need to write a new driver that supports the `SENSOR_CHAN_GAUGE_STATE_OF_CHARGE` sensor channel and contribute it to Zephyr or ZMK.
 

docs/docs/hardware-integration/bootloader/rp2.mdx

@@ -7,7 +7,7 @@ import BaseConfig from "./_base-config.md";
 
 The RP2040/RP2350 Bootloader is a [jump-to type bootloader](./index.mdx#jump-to-bootloaders), with some extra setup used to integrate with it.
 
-By default, when integrating this bootloader, a ["double tap reset to enter the bootloader"](../../../config/system.md#double-tap-to-bootloader) feature will be enabled, to help with designs that do not easily expose a BOOTSEL pin.
+By default, when integrating this bootloader, a ["double tap reset to enter the bootloader"](../../config/bootloader.md#double-tap-to-bootloader) feature will be enabled, to help with designs that do not easily expose a BOOTSEL pin.
 
 <BaseConfig />
 

docs/docs/hardware-integration/bootloader/stm32.mdx

@@ -8,7 +8,7 @@ import BaseConfig from "./_base-config.md";
 
 The [STM32 ROM Bootloader](https://www.st.com/resource/en/application_note/an2606-stm32-microcontroller-system-memory-boot-mode-stmicroelectronics.pdf) is a [jump-to type bootloader](./index.mdx#jump-to-bootloaders), with some extra setup used to integrate with it.
 
-By default, when integrating this bootloader, a ["double tap reset to enter the bootloader"](../../../config/system.md#double-tap-to-bootloader) feature will be enabled, to help with designs that do not easily expose a BOOT pin.
+By default, when integrating this bootloader, a ["double tap reset to enter the bootloader"](../../config/bootloader.md#double-tap-to-bootloader) feature will be enabled, to help with designs that do not easily expose a BOOT pin.
 
 <BaseConfig />
 

docs/docs/hardware-integration/dongle.mdx

@@ -6,7 +6,7 @@ sidebar_label: Keyboard Dongle
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-A bluetooth dongle can be added to any wireless keyboard running ZMK. The result is a [split keyboard](../../features/split-keyboards.md) with the dongle as ["central"](../../features/split-keyboards.md#central-and-peripheral-roles). There are a number of advantages to adding a dongle, but also some disadvantages:
+A bluetooth dongle can be added to any wireless keyboard running ZMK. The result is a [split keyboard](../features/split-keyboards.md) with the dongle as ["central"](../features/split-keyboards.md#central-and-peripheral-roles). There are a number of advantages to adding a dongle, but also some disadvantages:
 
 Benefits:
 
@@ -18,7 +18,7 @@ Disadvantages:
 - An extra [board](index.mdx#what-is-a-board) is needed (any BLE-capable board that ZMK supports will work).
 - The keyboard becomes unusable without the dongle.
 
-Depending on how the dongle is used, there are some additional [latency considerations](../../features/split-keyboards.md#latency-considerations) to keep in mind.
+Depending on how the dongle is used, there are some additional [latency considerations](../features/split-keyboards.md#latency-considerations) to keep in mind.
 The addition of the dongle adds an extra "hop" for the former central, increasing its latency to that of a peripheral. The other parts are unchanged latency-wise. There is also a commonly occurring case where the peripherals benefit.
 Assuming the dongle is connected to USB and the former central would have been connected via bluetooth to the host if the dongle wasn't present:
 
@@ -119,7 +119,7 @@ You will now need to find and copy your keyboard's matrix transform into the `my
 
 #### Matrix transform
 
-Navigate to the directory defining your keyboard (in-tree keyboards found [here](https://github.com/zmkfirmware/zmk/tree/main/app/boards), if your keyboard is a shield look under the `shields` subdirectory) and look through the [devicetree files](../../config/index.md) for nodes with `compatible = "zmk,matrix-transform";`.
+Navigate to the directory defining your keyboard (in-tree keyboards found [here](https://github.com/zmkfirmware/zmk/tree/main/app/boards), if your keyboard is a shield look under the `shields` subdirectory) and look through the [devicetree files](../config/index.md) for nodes with `compatible = "zmk,matrix-transform";`.
 This should look something like this:
 
 ```dts
@@ -141,7 +141,7 @@ Make a note of the label that the transform has, it will be used later. In the e
 
 #### Physical layout
 
-A full physical layout is necessary to allow your dongle to be used with [ZMK Studio](../../features/studio.md).
+A full physical layout is necessary to allow your dongle to be used with [ZMK Studio](../features/studio.md).
 If your keyboard is not Studio-ready or you have no interest in using ZMK Studio with your dongle, then this section is simplified significantly.
 
 <Tabs
@@ -299,16 +299,16 @@ include:
     cmake-args: -DCONFIG_ZMK_SPLIT=y -DCONFIG_ZMK_SPLIT_ROLE_CENTRAL=n
 ```
 
-You can then flash the firmware to your device as detailed in our [user setup](../../user-setup.mdx#installing-the-firmware) and [split keyboard](../../features/split-keyboards.md#building-and-flashing-firmware) pages.
+You can then flash the firmware to your device as detailed in our [user setup](../user-setup.mdx#install-the-firmware) and [split keyboard](../features/split-keyboards.md#building-and-flashing-firmware) pages.
 
 :::warning
-Before flashing your new firmware, you need to flash `settings_reset` [firmware](../../troubleshooting/connection-issues.mdx#building-a-reset-firmware) on all devices to ensure they can pair to each other.
+Before flashing your new firmware, you need to flash `settings_reset` [firmware](../troubleshooting/connection-issues.mdx#building-a-reset-firmware) on all devices to ensure they can pair to each other.
 :::
 
-To use your dongled keyboard with [ZMK Studio](../../features/studio.md), apply the instructions for [building with Studio](../../features/studio.md#building) to the dongle.
+To use your dongled keyboard with [ZMK Studio](../features/studio.md), apply the instructions for [building with Studio](../features/studio.md#building) to the dongle.
 
 If you ever want to "undongle" your keyboard, simply remove these CMake arguments and flash the resulting firmware (after a `settings_reset`).
 
 [^1]: If you have a custom dongle that uses an onboard MCU, then you will need to take a slightly different approach that isn't currently documented.
 
-[^2]: If you are building locally, you can append these flags to the end of the [build command](../local-toolchain/build-flash.mdx#cmake-arguments).
+[^2]: If you are building locally, you can append these flags to the end of the [build command](../development/local-toolchain/build-flash.mdx#cmake-arguments).

docs/docs/hardware-integration/encoders.md

@@ -18,12 +18,12 @@ In your configuration file you will need to add the following lines so that the
 These should be commented by default for encoders that are optional/can be swapped with switches, but can be uncommented if encoders are part of the default design.
 
 :::note
-If building locally for split boards, you may need to add these lines to the specific half's configuration file as well as the combined configuration file, see the [configuration overview](../../config/index.md) for details.
+If building locally for split boards, you may need to add these lines to the specific half's configuration file as well as the combined configuration file, see the [configuration overview](../config/index.md) for details.
 :::
 
 ## Devicetree File
 
-In your devicetree file you will need to define each sensor with their properties. For split keyboards, do this in the .dtsi file that is shared by all parts; otherwise do it in the .dts (for boards) or .overlay (shields) file, see [configuration overview](../../config/index.md#devicetree-files) for details. Add the following lines:
+In your devicetree file you will need to define each sensor with their properties. For split keyboards, do this in the .dtsi file that is shared by all parts; otherwise do it in the .dts (for boards) or .overlay (shields) file, see [configuration overview](../config/index.md#devicetree-files) for details. Add the following lines:
 
 ```dts
     left_encoder: encoder_left {
@@ -53,7 +53,7 @@ Once you have defined the encoder sensors, you will have to add them to the list
 
 In this example, a `left_encoder` and `right_encoder` are both added. Additional encoders can be added with spaces separating each, and the order they are added here determines the order in which you define their behavior in your keymap.
 
-In addition, a default value for the number of times the sensors trigger the bound behavior per full rotation is set via the `triggers-per-rotation` property. See [Encoders Config](../../config/encoders.md#devicetree) for more details.
+In addition, a default value for the number of times the sensors trigger the bound behavior per full rotation is set via the `triggers-per-rotation` property. See [Encoders Config](../config/encoders.md#devicetree) for more details.
 
 Add the following lines to the .dts/.overlay file that contains the encoder to enable it:
 
@@ -73,4 +73,4 @@ Add the following line to your keymap file to add default encoder behavior bindi
 sensor-bindings = <&inc_dec_kp C_VOL_UP C_VOL_DN>;
 ```
 
-Add additional bindings as necessary to match the default number of encoders on your board. See the [Encoders](../../features/encoders.md) and [Keymaps](../../keymaps/index.mdx) documentation pages for more details.
+Add additional bindings as necessary to match the default number of encoders on your board. See the [Encoders](../features/encoders.md) and [Keymaps](../keymaps/index.mdx) documentation pages for more details.

docs/docs/hardware-integration/hardware-metadata-files.md

@@ -95,7 +95,7 @@ Boards and shields should document the sets of hardware features found on them u
 - `encoder` - Indicates the hardware contains one or more rotary encoders.
 - `underglow` - Indicates the hardware includes underglow LEDs.
 - `backlight` - Indicates the hardware includes backlight LEDs.
-- `studio` - Indicates the keyboard is ready to use with [ZMK Studio](../../features/studio.md).
+- `studio` - Indicates the keyboard is ready to use with [ZMK Studio](../features/studio.md).
 - `pointer` (future) - Used to indicate the hardware includes one or more pointer inputs, e.g. joystick, touchpad, or trackpoint.
 
 ### Siblings

docs/docs/hardware-integration/includes/_sideband-direct.md

@@ -1,8 +1,8 @@
 ### KScan sideband behavior
 
-The kscan sideband behavior driver will be used to trigger the [soft off behavior](../../../keymaps/behaviors/soft-off.md) "out of band" from the normal keymap processing. To do so, it will decorate/wrap an underlying kscan driver.
+The kscan sideband behavior driver will be used to trigger the [soft off behavior](../../keymaps/behaviors/soft-off.md) "out of band" from the normal keymap processing. To do so, it will decorate/wrap an underlying kscan driver.
 
-With a simple direct pin setup, the [direct kscan](../../../config/kscan.md) driver can be used with a [GPIO key](#gpio-key), to make a small "side matrix":
+With a simple direct pin setup, the [direct kscan](../../config/kscan.md) driver can be used with a [GPIO key](#gpio-key), to make a small "side matrix":
 
 ```dts
 / {
@@ -34,4 +34,4 @@ With that in place, the kscan sideband behavior will wrap the new driver:
 };
 ```
 
-As the kscan used only has a single key, both column and row are set to 0. The properties of the `kscan-sideband-behaviors` node can be found in the [appropriate configuration section](../../../config/kscan.md#kscan-sideband-behavior-driver).
+As the kscan used only has a single key, both column and row are set to 0. The properties of the `kscan-sideband-behaviors` node can be found in the [appropriate configuration section](../../config/kscan.md#kscan-sideband-behavior-driver).

docs/docs/hardware-integration/includes/_sideband-matrix.md

@@ -1,6 +1,6 @@
 ### KScan sideband behavior
 
-The kscan sideband behavior driver will be used to trigger the [soft off behavior](../../../keymaps/behaviors/soft-off.md) "out of band" from the normal keymap processing. To do so, it will decorate/wrap an underlying kscan driver.
+The kscan sideband behavior driver will be used to trigger the [soft off behavior](../../keymaps/behaviors/soft-off.md) "out of band" from the normal keymap processing. To do so, it will decorate/wrap an underlying kscan driver.
 
 For the matrix-integrated approach you will supplement the existing kscan matrix by adding the additional pin as another entry in
 the `row-gpios`/`col-gpios` for whichever pins are used to read the matrix state. This approach requires a matrix transform to be present. As an example, consider the following existing kscan matrix:
@@ -63,4 +63,4 @@ With that in place, you would decorate the kscan driver:
 };
 ```
 
-Critically, the `column` and `row` values would correspond to the location of the added entry. The properties of the `kscan-sideband-behaviors` node can be found in the [appropriate configuration section](../../../config/kscan.md#kscan-sideband-behavior-driver).
+Critically, the `column` and `row` values would correspond to the location of the added entry. The properties of the `kscan-sideband-behaviors` node can be found in the [appropriate configuration section](../../config/kscan.md#kscan-sideband-behavior-driver).

docs/docs/hardware-integration/includes/_sideband-wakeup-direct.md

@@ -1,6 +1,6 @@
 ### KScan sideband behavior
 
-With a simple direct pin setup, the [direct kscan](../../../config/kscan.md) driver can be used with a [GPIO key](#gpio-key), to make a small "side matrix":
+With a simple direct pin setup, the [direct kscan](../../config/kscan.md) driver can be used with a [GPIO key](#gpio-key), to make a small "side matrix":
 
 ```dts
 / {
@@ -25,4 +25,4 @@ The kscan sideband behavior needs to wrap the new driver to enable it:
 };
 ```
 
-The properties of the `kscan-sideband-behaviors` node can be found in the [appropriate configuration section](../../../config/kscan.md#kscan-sideband-behavior-driver).
+The properties of the `kscan-sideband-behaviors` node can be found in the [appropriate configuration section](../../config/kscan.md#kscan-sideband-behavior-driver).

docs/docs/hardware-integration/includes/_soft-off-behavior.md

@@ -1,6 +1,6 @@
 ### Soft off behavior instance
 
-Behind the scenes, a hardware dedicated GPIO pin utilizes the [soft off behavior](../../../keymaps/behaviors/soft-off.md) to trigger entering the soft-off state. To use said behavior outside of a keymap, add an instance of the behavior to your `.overlay`/`.dts` file:
+Behind the scenes, a hardware dedicated GPIO pin utilizes the [soft off behavior](../../keymaps/behaviors/soft-off.md) to trigger entering the soft-off state. To use said behavior outside of a keymap, add an instance of the behavior to your `.overlay`/`.dts` file:
 
 ```dts
 / {

docs/docs/hardware-integration/includes/_soft-off-waker.md

@@ -13,5 +13,5 @@ We need to add another device which will be enabled only when the keyboard is go
 };
 ```
 
-The properties for the `gpio-key-wakeup-trigger` node can be found in the [appropriate configuration section](../../../config/power.md#gpio-key-wakeup-trigger).
+The properties for the `gpio-key-wakeup-trigger` node can be found in the [appropriate configuration section](../../config/power.md#gpio-key-wakeup-trigger).
 In particular, note the `extra-gpios` property containing the MCU output pins of any keys used to wake the keyboard (for a `col2row` matrix, these are your columns).

docs/docs/hardware-integration/index.mdx

@@ -12,10 +12,10 @@ Please see pages in the sidebar for guides and reference that describe different
 The foundational elements needed to get a specific keyboard working with ZMK can be broken down into:
 
 - A [physical layout](physical-layouts.md) that describes the electrical and physical structure of the keyboard, referring to:
-  - A [kscan driver](../../config/kscan.md), which most frequently uses `compatible = "zmk,kscan-gpio-matrix"` for GPIO matrix based keyboards, or `compatible = "zmk,kscan-gpio-direct"` for direct wires.
+  - A [kscan driver](../config/kscan.md), which most frequently uses `compatible = "zmk,kscan-gpio-matrix"` for GPIO matrix based keyboards, or `compatible = "zmk,kscan-gpio-direct"` for direct wires.
-  - A [matrix transform](../../config/layout.md), which defines how the kscan row/column events are translated into logical "key positions".
+  - A [matrix transform](../config/layout.md), which defines how the kscan row/column events are translated into logical "key positions".
-  - An [optional description](physical-layouts.md#optional-keys-property) of physical key positions and sizes, in order to visualize the keyboard accurately in [ZMK Studio](../../features/studio.md).
+  - An [optional description](physical-layouts.md#optional-keys-property) of physical key positions and sizes, in order to visualize the keyboard accurately in [ZMK Studio](../features/studio.md).
-- A [keymap](../../keymaps/index.mdx), which binds each key position to a behavior, e.g. key press, mod-tap, momentary layer, in a set of layers.
+- A [keymap](../keymaps/index.mdx), which binds each key position to a behavior, e.g. key press, mod-tap, momentary layer, in a set of layers.
 - Other, optional configuration items to support features such as encoders or lighting systems.
 
 These core architectural elements are defined per-keyboard, and _where_ they are defined depends on the specifics of how that keyboard is structured.
@@ -41,7 +41,7 @@ The shield is usually the big PCB containing all the keys.
 
 ### Why not just "keyboard"?
 
-["Composite" keyboards](../../hardware.mdx#composite) are keyboards which use a separate small PCB MCU module for its "brains".
+["Composite" keyboards](../hardware.mdx#composite) are keyboards which use a separate small PCB MCU module for its "brains".
 In such keyboards, the [shield](#what-is-a-shield) is a brainless shell containing all the keys, RGB LEDs, encoders etc.
 It typically maps all of these features to a standard pin footprint, such as the Pro Micro pinout.
 
@@ -52,7 +52,7 @@ But each board comes with its own features (MCU, flash, BLE, etc.) which must al
 Therefore in ZMK, board and shield are considered two different (but related) entities so that it is easier to mix and match them, and they are combined during a ZMK build.
 This provides the modularity to be able to use composite keyboards with different compatible controllers.
 
-Note that ["self-contained" keyboards](../../hardware.mdx#onboard) only have a single PCB which includes the "brains" (MCU) onboard.
+Note that ["self-contained" keyboards](../hardware.mdx#onboard) only have a single PCB which includes the "brains" (MCU) onboard.
 In ZMK, these have no shield, only a board.
 
 ## Organization Overview
@@ -67,11 +67,11 @@ values={[
 
 <TabItem value="self-contained">
 
-For a [self-contained keyboard](../../hardware.mdx#onboard) that includes the microprocessor, all of the above architecture components are included in the Zephyr _board_ definition and no shield is defined.
+For a [self-contained keyboard](../hardware.mdx#onboard) that includes the microprocessor, all of the above architecture components are included in the Zephyr _board_ definition and no shield is defined.
 You can see an example for the [Planck V6](https://github.com/zmkfirmware/zmk/tree/main/app/boards/olkb/planck) board directory.
 
-With this type of keyboard, the full ZMK definition for the keyboard exists in the `<board_root>/boards/<vendor or designer>/<keyboard_name>` directory where `<board_root>` is `zmk/app` or a [module](../../features/modules.mdx) root, e.g. `zmk/app/boards/olkb/planck/`.
+With this type of keyboard, the full ZMK definition for the keyboard exists in the `<board_root>/boards/<vendor or designer>/<keyboard_name>` directory where `<board_root>` is `zmk/app` or a [module](../features/modules.mdx) root, e.g. `zmk/app/boards/olkb/planck/`.
-In that directory you'll have the following files, where there can be multiples of files with `<board_name>`s, corresponding to each keyboard part for [split keyboards](../../features/split-keyboards.md):
+In that directory you'll have the following files, where there can be multiples of files with `<board_name>`s, corresponding to each keyboard part for [split keyboards](../features/split-keyboards.md):
 
 ```
 <keyboard_name>
@@ -89,14 +89,14 @@ These files include [base Kconfig files](https://docs.zephyrproject.org/4.1.0/bu
 
 - A `Kconfig.<board_name>` file that defines the toplevel [Kconfig](https://docs.zephyrproject.org/4.1.0/build/kconfig/index.html) items for the board, including selecting the corresponding SoC Kconfig setting.
 - A `Kconfig.defconfig` file that sets some initial defaults when building this keyboard. This usually includes:
-  - Setting [`ZMK_KEYBOARD_NAME`](../../config/system.md#general) to a value, for the product name to be used for USB/BLE info
+  - Setting [`ZMK_KEYBOARD_NAME`](../config/system.md#general) to a value, for the product name to be used for USB/BLE info
 
-[Configuration files](../../config/index.md#kconfig-files) that set the visible Kconfig symbols:
+[Configuration files](../config/index.md#kconfig-files) that set the visible Kconfig symbols:
 
 - A `<board_name>_defconfig` file that forces specific Kconfig settings that are specific to this hardware configuration.
   These tend to be settings enabling various drivers or features, e.g. GPIO, USB support, or memory settings for ZMK Studio.
 
-[Devicetree files](../../config/index.md#devicetree-files):
+[Devicetree files](../config/index.md#devicetree-files):
 
 - `<board_name>.dts` which contains all the devicetree definitions[^1], including but not limited to:
   - An `#include` line that pulls in the specific microprocessor that is used, e.g. `#include <st/f3/stm32f303Xc.dtsi>`,
@@ -120,11 +120,11 @@ See also our [new board guide](new-board.md) for information on creating a ZMK-c
 </TabItem>
 <TabItem value="composite">
 
-Keyboards that require an add-on board to operate are [composite keyboards](../../hardware.mdx#composite), where the ZMK integration pieces are placed in the _shield_ definition for that keyboard.
+Keyboards that require an add-on board to operate are [composite keyboards](../hardware.mdx#composite), where the ZMK integration pieces are placed in the _shield_ definition for that keyboard.
 This allows users to swap in different boards that use the same interconnect (e.g. Pro Micro RP2040, or nice!nano) and build a firmware the matches their actual combination of physical components.
 
-With this type of keyboard, the partial definition for the keyboard exists in the `<board_root>/boards/shields/<keyboard_name>` directory where `<board_root>` is `zmk/app` or a [module](../../features/modules.mdx) root, e.g. `zmk/app/boards/shields/clueboard_california/`.
+With this type of keyboard, the partial definition for the keyboard exists in the `<board_root>/boards/shields/<keyboard_name>` directory where `<board_root>` is `zmk/app` or a [module](../features/modules.mdx) root, e.g. `zmk/app/boards/shields/clueboard_california/`.
-In that directory, you'll have the following files, where there can be multiple `<shield_name>`s, corresponding to each keyboard part for [split keyboards](../../features/split-keyboards.md):
+In that directory, you'll have the following files, where there can be multiple `<shield_name>`s, corresponding to each keyboard part for [split keyboards](../features/split-keyboards.md):
 
 ```
 <keyboard_name>
@@ -140,7 +140,7 @@ These files include [base Kconfig files](new-shield.mdx#base-kconfig-files):
 - A `Kconfig.shield` that defines the toplevel Kconfig value for the shield, which uses a supplied utility to function to default the value based on the shield list, e.g. `def_bool $(shields_list_contains,clueboard_california)`.
 - A `Kconfig.defconfig` file to set default values for settings like `ZMK_KEYBOARD_NAME`
 
-[Devicetree files](../../config/index.md#devicetree-files):
+[Devicetree files](../config/index.md#devicetree-files):
 
 - A `<shield_name>.overlay` file which is a devicetree overlay file[^1], containing definitions including but not limited to:
   - Kscan, matrix transform and physical layout devicetree nodes as described above, where the kscan node uses the interconnect [nexus node](https://docs.zephyrproject.org/4.1.0/hardware/porting/shields.html#gpio-nexus-nodes) aliases such as `&pro_micro` for GPIO pins.

docs/docs/hardware-integration/lighting/backlight.mdx

@@ -7,7 +7,7 @@ description: Lighting system that controls an array of single-color LEDs.
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-Please see [lighting feature page](../../../features/lighting.md#backlight) for an introduction on the feature.
+Please see [lighting feature page](../../features/lighting.md#backlight) for an introduction on the feature.
 
 <Tabs
   defaultValue="shieldpin"

docs/docs/hardware-integration/lighting/led-indicators.md

@@ -115,4 +115,4 @@ You can also control multiple LEDs from the same indicator:
 
 ## LED Behavior
 
-See the [feature page](../../../features/led-indicators.md) and [configuration page](../../../config/led-indicators.md) for details on configuring LED brightness according to the indicator state.
+See the [feature page](../../features/led-indicators.md) and [configuration page](../../config/led-indicators.md) for details on configuring LED brightness according to the indicator state.

docs/docs/hardware-integration/lighting/underglow.md

@@ -4,7 +4,7 @@ sidebar_label: RGB Underglow
 description: Lighting system that controls strips of RGB LEDs.
 ---
 
-Please see [lighting feature page](../../../features/lighting.md#rgb-underglow) for an introduction on the feature.
+Please see [lighting feature page](../../features/lighting.md#rgb-underglow) for an introduction on the feature.
 
 Support for RGB underglow is always added to a board, not a shield. This is because the LED strip drivers rely on hardware-specific interfaces (e.g. SPI, I2S) and configurations, which shields do not control.
 See the documentation page on [pin control](../pinctrl.mdx) for detailed information on setting up pins for hardware protocols such as SPI or PIO that are used for LED strips.

docs/docs/hardware-integration/new-board.md

@@ -11,7 +11,7 @@ Some keyboards are boards but also have interconnects for modular add-ons. These
 
 ## Boards Included in ZMK
 
-Boards with interconnects can be considered for inclusion to the tree of ZMK. If this is your aim, it is vital that you read through our [clean room policy](../contributing/clean-room.md).
+Boards with interconnects can be considered for inclusion to the tree of ZMK. If this is your aim, it is vital that you read through our [clean room policy](../development/contributing/clean-room.md).
 
 Boards with interconnects that are included with ZMK are generally:
 
@@ -43,9 +43,9 @@ Follow these steps to create your new repository:
 
 The repository is a combination of the directories and files required of a ZMK config, and those required of a shield module.
 This enables the use of GitHub Actions to test that the shield is defined correctly.
-See also the page on [module creation](../module-creation.md) for a reference on exactly which file structure and files are required for a ZMK keyboard module.
+See also the page on [module creation](../development/module-creation.md) for a reference on exactly which file structure and files are required for a ZMK keyboard module.
 
-We recommend that you take this moment to name your module according to our [convention](../module-creation.md), i.e. your `zephyr/module.yml` file should begin with
+We recommend that you take this moment to name your module according to our [convention](../development/module-creation.md), i.e. your `zephyr/module.yml` file should begin with
 
 ```yaml title="zephyr/module.yml"
 name: zmk-keyboard-<keyboard_name>
@@ -182,6 +182,6 @@ See [here](./bootloader/index.mdx) for bootloader instructions for other SoCs. D
 
 ## Next Steps
 
-If your board is a keyboard, continue from [the `Kconfig.defconfig` step](https://zmk.dev/docs/development/hardware-integration/new-shield?keyboard-type=unibody#kconfigdefconfig) of the new shield guide. Use your ZMK variant's devicetree instead of the overlay file which would be used for a shield.
+If your board is a keyboard, continue from [the `Kconfig.defconfig` step](https://zmk.dev/docs/hardware-integration/new-shield?keyboard-type=unibody#kconfigdefconfig) of the new shield guide. Use your ZMK variant's devicetree instead of the overlay file which would be used for a shield.
 
-If your board is a board with an interconnect, your next step should be to write a [tester shield](../../troubleshooting/hardware-issues.mdx#identifying-issues). Such a shield should be the bare minimum shield to verify that your board works with ZMK.
+If your board is a board with an interconnect, your next step should be to write a [tester shield](../troubleshooting/hardware-issues.mdx#identifying-issues). Such a shield should be the bare minimum shield to verify that your board works with ZMK.

docs/docs/hardware-integration/new-shield.mdx

@@ -44,7 +44,7 @@ This guide will walk through the steps necessary to add ZMK support for a keyboa
 
 The high level steps are:
 
-- Create a new [ZMK module](../module-creation.md) to contain your shield.
+- Create a new [ZMK module](../development/module-creation.md) to contain your shield.
 - Create a new shield directory.
 - Add the base Kconfig files.
 - Add the shield overlay file defining:
@@ -54,7 +54,7 @@ The high level steps are:
 - Add a default keymap, which users can override in their own configs as needed.
 - Add a `<my_shield>.zmk.yml` metadata file to document the high level details of your shield, and the features it supports.
 
-Many of the above files will differ depending on whether your keyboard is a unibody or is [split into multiple parts](../../features/split-keyboards.md).
+Many of the above files will differ depending on whether your keyboard is a unibody or is [split into multiple parts](../features/split-keyboards.md).
 
 After adding ZMK support for a basic shield using this guide, check the sidebar for guides on adding any additional features (such as encoders) that your keyboard has.
 It may be helpful to review the upstream [shields documentation](https://docs.zephyrproject.org/4.1.0/hardware/porting/shields.html#shields) to get a proper understanding of the underlying system before continuing.
@@ -63,7 +63,7 @@ It may be helpful to review the upstream [shields documentation](https://docs.ze
 When writing your shield, please be aware of [licensing](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository):
 
 - If you reference code or other items that are under a copyleft license (e.g. GNU GPLv2, used by QMK) as a reference, you must license your shield under a compatible copyleft license.
-- If you license anything under a copyleft license, it cannot be referenced by anyone working on ZMK (see our [clean room policy](../contributing/clean-room.md)).
+- If you license anything under a copyleft license, it cannot be referenced by anyone working on ZMK (see our [clean room policy](../development/contributing/clean-room.md)).
 
 We generally recommend licensing your shield under MIT, if you don't have a particular incentive to do otherwise.
 :::
@@ -89,9 +89,9 @@ Follow these steps to create your new repository:
 
 The repository is a combination of the directories and files required of a ZMK config, and those required of a shield module.
 This enables the use of GitHub Actions to test that the shield is defined correctly.
-See also the page on [module creation](../module-creation.md) for a reference on exactly which file structure and files are required for a ZMK keyboard module.
+See also the page on [module creation](../development/module-creation.md) for a reference on exactly which file structure and files are required for a ZMK keyboard module.
 
-We recommend that you take this moment to name your module according to our [convention](../module-creation.md), i.e. your `zephyr/module.yml` file should begin with
+We recommend that you take this moment to name your module according to our [convention](../development/module-creation.md), i.e. your `zephyr/module.yml` file should begin with
 
 ```yaml title="zephyr/module.yml"
 name: zmk-keyboard-<keyboard_name>
@@ -108,7 +108,7 @@ mkdir boards/shields/<keyboard_name>
 ## Base Kconfig Files
 
 :::tip[Example shields]
-You can check out the [`shields` folder](https://github.com/zmkfirmware/zmk/tree/main/app/boards/shields) in the ZMK repo that houses [the in-tree supported shields](../../hardware.mdx) in order to copy and modify as a starting point.
+You can check out the [`shields` folder](https://github.com/zmkfirmware/zmk/tree/main/app/boards/shields) in the ZMK repo that houses [the in-tree supported shields](../hardware.mdx) in order to copy and modify as a starting point.
 :::
 
 There are two required [Kconfig](https://docs.zephyrproject.org/4.1.0/build/kconfig/index.html) files that need to be created for your new keyboard shield to get it picked up for ZMK, `Kconfig.shield` and `Kconfig.defconfig`.
@@ -208,7 +208,7 @@ endif
 ### User Configuration Files
 
 In addition to the `Kconfig.shield` and `Kconfig.defconfig` files, many shields will also define a user configuration file called `my_keyboard.conf`.
-This file exists to provide "suggestions" of [configuration settings](../../config/index.md) for a user to select, such as enabling deep sleep.
+This file exists to provide "suggestions" of [configuration settings](../config/index.md) for a user to select, such as enabling deep sleep.
 Note that the name should match the shield/part name defined in the [Kconfig.shield file](#kconfigshield).
 
 :::warning
@@ -231,7 +231,7 @@ Split keyboards can have multiple `.conf` files, one for each part. For example:
 In most case you'll only need to use the .conf file that affects both halves of a split board.
 
 :::note
-The shared configuration in `my_keyboard.conf` is only applied when you are building with a [`zmk-config` folder](../local-toolchain/build-flash.mdx#building-from-zmk-config-folder) and it is present at `config/my_keyboard.conf`.
+The shared configuration in `my_keyboard.conf` is only applied when you are building with a [`zmk-config` folder](../development/local-toolchain/build-flash.mdx#building-from-zmk-config-folder) and it is present at `config/my_keyboard.conf`.
 :::
 
 </TabItem>
@@ -246,7 +246,7 @@ There are three main things that need to be defined in this file:
 
 - Your keyboard scan (kscan) driver, which determines which GPIO pins to scan for key press events
 - Your matrix transform, which acts as a "bridge" between the kscan and the keymap
-- Your physical layout, which aggregates the above and (optionally) defines physical key positions so that the keyboard can be used with [ZMK Studio](../../features/studio.md).
+- Your physical layout, which aggregates the above and (optionally) defines physical key positions so that the keyboard can be used with [ZMK Studio](../features/studio.md).
 
 <SplitInvisTabs>
 <TabItem value="unibody">
@@ -280,7 +280,7 @@ To use GPIO pins that are not part of the interconnects as described above, you
 For instance, pins numbered `PX.Y` in nRF52840-based boards can be referred to via `&gpioX Y` labels.
 An example is `&gpio1 7` for the `P1.07` pin that the nice!nano exposes in the middle of the board.
 
-The [Keyboard Scan configuration documentation](../../config/kscan.md) has the full details on configuring the kscan driver.
+The [Keyboard Scan configuration documentation](../config/kscan.md) has the full details on configuring the kscan driver.
 
 <SplitTabs>
 <TabItem value="unibody">
@@ -450,7 +450,7 @@ The matrix transform is also used to "correct" pin orderings into something that
 
 See the [in-tree keyboards](https://github.com/zmkfirmware/zmk/tree/main/app/boards/shields) that ZMK defines for examples of more complex matrix transformations.
 
-Also see the [matrix transform section](../../config/layout.md#matrix-transform) in the Keyboard Scan configuration documentation for further details and examples of matrix transforms.
+Also see the [matrix transform section](../config/layout.md#matrix-transform) in the Keyboard Scan configuration documentation for further details and examples of matrix transforms.
 
 ### Physical Layout
 
@@ -460,7 +460,7 @@ Physical layouts organize the matrix transform, kscan and optionally the physica
 <Tabs groupId="physical-layouts" queryString defaultValue="basic">
   <TabItem value="basic" label="Basic">
 
-If you are not planning to add support for [ZMK Studio](../../features/studio.md), you can add a `zmk,physical-layout`-compatible node for each physical layout your keyboard supports:
+If you are not planning to add support for [ZMK Studio](../features/studio.md), you can add a `zmk,physical-layout`-compatible node for each physical layout your keyboard supports:
 
 ```dts
 / {
@@ -478,7 +478,7 @@ These nodes should be placed in `my_keyboard.overlay` for unibody keyboards and
   </TabItem>
   <TabItem value="studio" label="With ZMK Studio Support">
 
-If you are planning to add support for [ZMK Studio](../../features/studio.md), you should follow the [physical layouts documentation](physical-layouts.md) to create a new file `my_keyboard-layouts.dtsi` which includes the physical layout definitions.
+If you are planning to add support for [ZMK Studio](../features/studio.md), you should follow the [physical layouts documentation](physical-layouts.md) to create a new file `my_keyboard-layouts.dtsi` which includes the physical layout definitions.
 Once you have finished defining your physical layouts, import the `my_keyboard-layouts.dtsi` file at the top of your `my_keyboard.overlay` file (unibody) or `my_keyboard.dtsi` file (split).
 
 ```dts
@@ -501,7 +501,7 @@ Set the `chosen` node to a defined "default" physical layout. This should also b
 };
 ```
 
-If you define multiple physical layouts, users can select a different layout by overriding the `zmk,physical-layout` chosen node in their keymap file or by using [ZMK Studio](../../features/studio.md) if your board is compatible with it.
+If you define multiple physical layouts, users can select a different layout by overriding the `zmk,physical-layout` chosen node in their keymap file or by using [ZMK Studio](../features/studio.md) if your board is compatible with it.
 
 :::note
 If all of your physical layouts use the same `kscan` node under the hood, you can skip setting the `kscan` property on each layout and instead assign the `zmk,kscan` chosen node to your single kscan instance:
@@ -524,7 +524,7 @@ If all of your physical layouts use the same `kscan` node under the hood, you ca
 <TabItem value="unibody">This is only required for wired split keyboards.</TabItem>
 <TabItem value="split">
 
-If testing the experimental [wired split](../../features/split-keyboards.md) support, you should assign a [predefined](./pinctrl.mdx#predefined-nodes) or [pinctrl configured](./pinctrl.mdx) UART to the `device` property of a new node with `compatible` value of `"zmk,wired-split"`:
+If testing the experimental [wired split](../features/split-keyboards.md) support, you should assign a [predefined](./pinctrl.mdx#predefined-nodes) or [pinctrl configured](./pinctrl.mdx) UART to the `device` property of a new node with `compatible` value of `"zmk,wired-split"`:
 
 ```dts
 / {
@@ -535,7 +535,7 @@ If testing the experimental [wired split](../../features/split-keyboards.md) sup
 };
 ```
 
-See the [wired split](../../config/split.md#wired-split) configuration for more details.
+See the [wired split](../config/split.md#wired-split) configuration for more details.
 
 For wireless split keyboards, this step should be skipped, especially since the UART pins on your controller might already be in use for other functionality.
 
@@ -573,8 +573,8 @@ Here is an example simple keymap for a 3x3 macropad, with only one layer:
 ```
 
 The keymap should match the order of the keys in the [matrix transform](#matrix-transform) exactly, left to right, top to bottom (they are both 1 dimensional arrays rearranged with newline characters for better legibility).
-See [Keymaps](../../keymaps/index.mdx) for information on defining keymaps in ZMK.
+See [Keymaps](../keymaps/index.mdx) for information on defining keymaps in ZMK.
-If you wish to use [ZMK Studio](../../features/studio.md) with your keyboard, make sure to assign the [ZMK Studio unlocking behavior](../../keymaps/behaviors/studio-unlock.md) to a key in your keymap.
+If you wish to use [ZMK Studio](../features/studio.md) with your keyboard, make sure to assign the [ZMK Studio unlocking behavior](../keymaps/behaviors/studio-unlock.md) to a key in your keymap.
 
 ## Metadata
 
@@ -604,12 +604,12 @@ See [Hardware Metadata Files](hardware-metadata-files.md) for the full details.
 ## Testing
 
 Once you've defined everything as described above, you can build your firmware to make sure everything is working.
-If you wish to test that your keyboard works with [ZMK Studio](../../features/studio.md), you'll also need to follow the [instructions for enabling Studio](../../features/studio.md#building).
+If you wish to test that your keyboard works with [ZMK Studio](../features/studio.md), you'll also need to follow the [instructions for enabling Studio](../features/studio.md#building).
 
 ### GitHub Actions
 
 To use GitHub Actions to test, push the files defining the keyboard to GitHub.
-Next, [update the `build.yaml`](../../customization.md#building-additional-keyboards) of your `zmk-config` to build your keyboard.
+Next, [update the `build.yaml`](../customization.md#building-additional-keyboards) of your `zmk-config` to build your keyboard.
 
 - If your shield is defined in your `zmk-config`, then the shield should start building.
 - If the shield is defined in a separate module, you will need to [adjust your `west.yml` to reference the module](https://zmk.dev/docs/features/modules#building-with-modules).
@@ -617,5 +617,5 @@ Next, [update the `build.yaml`](../../customization.md#building-additional-keybo
 ### Local Toolchain
 
 You can also use a local toolchain setup to test your keyboard.
-Follow [our guide for getting set up](../local-toolchain/setup/index.md), then follow the [instructions for building and flashing locally](../local-toolchain/build-flash.mdx).
+Follow [our guide for getting set up](../development/local-toolchain/setup/index.md), then follow the [instructions for building and flashing locally](../development/local-toolchain/build-flash.mdx).
 You will need to specify the module of your keyboard when building.

docs/docs/hardware-integration/physical-layouts.md

@@ -6,8 +6,8 @@ toc_max_heading_level: 4
 A physical layout is a devicetree entity that aggregates all details about a certain possible keyboard layout.
 It contains:
 
-- A [keyboard scan (kscan) driver](../../config/kscan.md)
+- A [keyboard scan (kscan) driver](../config/kscan.md)
-- A [matrix transform](../../config/layout.md#matrix-transform)
+- 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`.
@@ -35,11 +35,11 @@ Every physical layout needs a matrix transform, and optionally can also have a k
 };
 ```
 
-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.
+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
 
-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.
+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:
 
@@ -171,7 +171,7 @@ If necessary, you can also define multiple kscan instances.
 
 ### Position Map
 
-When switching between layouts using [ZMK Studio](../../features/studio.md), an attempt is made to automatically infer bindings for the keys in the new layout from the old layout. Keys with the same physical key properties are given the same binding. This approach has some limitations, so for more accurate transference of bindings a position map is used.
+When switching between layouts using [ZMK Studio](../features/studio.md), an attempt is made to automatically infer bindings for the keys in the new layout from the old layout. Keys with the same physical key properties are given the same binding. This approach has some limitations, so for more accurate transference of bindings a position map is used.
 
 :::warning
 
@@ -203,9 +203,9 @@ A child node is defined for every layout the keyboard can have. The `positions`
 
 When switching from one layout to another, say from layout 1 to layout 2, the _orderings_ found in the `positions` arrays are used. The first key in the `positions` array of layout 2 is given the binding assigned to the first key in the `positions` array of layout 1, the second key in the `positions` array of layout 2 is given the binding assigned to the second key in the `positions` array of layout 1, and so on.
 
-The position map should be marked as `complete` if all desired binding transfers are defined within it. Otherwise, [ZMK Studio](../../features/studio.md) will continue to automatically determine assignments for keys not listed in the position map. See [this example non-complete position map](#example-non-complete-position-map) for why this could be useful.
+The position map should be marked as `complete` if all desired binding transfers are defined within it. Otherwise, [ZMK Studio](../features/studio.md) will continue to automatically determine assignments for keys not listed in the position map. See [this example non-complete position map](#example-non-complete-position-map) for why this could be useful.
 
-See also the [configuration section on position maps](../../config/layout.md#physical-layout-position-map).
+See also the [configuration section on position maps](../config/layout.md#physical-layout-position-map).
 
 :::tip
 
@@ -257,7 +257,7 @@ Next write the child nodes for every other layout with respect to the reference.
 
 Consider the following macropad/numpad with two physical layouts:
 
-![A 4x5 numpad/macropad](../../assets/hardware-integration/numpad.svg)
+![A 4x5 numpad/macropad](../assets/hardware-integration/numpad.svg)
 
 Let us first consider each side individually. The "reference" position map of the left side would look like this:
 

docs/docs/hardware-integration/pointing.mdx

@@ -7,10 +7,10 @@ import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
 ZMK's pointing device support builds upon the Zephyr [input API](https://docs.zephyrproject.org/4.1.0/services/input/index.html) to offer pointing/mouse functionality with various hardware.
-A limited number of input drivers are available in the Zephyr version currently used by ZMK, but additional drivers can be found in [external modules](../../features/modules.mdx) for a variety of hardware.
+A limited number of input drivers are available in the Zephyr version currently used by ZMK, but additional drivers can be found in [external modules](../features/modules.mdx) for a variety of hardware.
 
-Pointing devices are also supported on split peripherals, with some additional configuration using the [input split device](../../config/pointing.md#input-split).
+Pointing devices are also supported on split peripherals, with some additional configuration using the [input split device](../config/pointing.md#input-split).
-The configuration details will thus vary depending on if you are adding a pointing device to a [split peripheral](../../features/split-keyboards.md#central-and-peripheral-roles) as opposed to a unibody keyboard or split central part.
+The configuration details will thus vary depending on if you are adding a pointing device to a [split peripheral](../features/split-keyboards.md#central-and-peripheral-roles) as opposed to a unibody keyboard or split central part.
 
 export const SplitTabs = (props) => (
   <Tabs
@@ -81,7 +81,7 @@ The specifics of the properties required to set for a given driver will vary; al
 ## Listener and Input Split Device
 
 Every input device needs an associated listener added that listens for events from the device and processes them before sending the events to the host using a HID mouse report.
-See [input listener configuration](../../config/pointing.md#input-listener) for the full details.
+See [input listener configuration](../config/pointing.md#input-listener) for the full details.
 
 If your pointing device is on a split peripheral part, you also need to define and use an input split device on all keyboard parts.
 
@@ -246,7 +246,7 @@ Here we first include the shared file, and then enable the input listener that i
 
 Some physical pointing devices may be generating input events that need adjustment before being sent to hosts.
 For example a trackpad might be integrated into a keyboard rotated 90° and need the X/Y data adjusted appropriately.
-This can be accomplished with [input processors](../../keymaps/input-processors/index.md).
+This can be accomplished with [input processors](../keymaps/input-processors/index.md).
 As an example, you could enhance the listener defined in the previous section with an input processor that inverts and swaps the X/Y axes:
 
 ```dts
@@ -263,7 +263,7 @@ As an example, you could enhance the listener defined in the previous section wi
 
 ## Configuration Setting
 
-If your keyboard hardware includes a pointing device by default, you can enable the [`ZMK_POINTING` config](../../config/pointing.md#general) in your keyboard definition.
+If your keyboard hardware includes a pointing device by default, you can enable the [`ZMK_POINTING` config](../config/pointing.md#general) in your keyboard definition.
 You can do that in your [`Kconfig.defconfig` file](new-shield.mdx#kconfigdefconfig), where you can also enable the config for the communication protocol (e.g. [SPI](https://docs.zephyrproject.org/4.1.0/kconfig.html#CONFIG_SPI), [I2C](https://docs.zephyrproject.org/4.1.0/hardware/peripherals/i2c.html#configuration-options)) used by the pointing device:
 
 <SplitTabs>

docs/docs/hardware-integration/shift-registers.md

@@ -15,7 +15,7 @@ To understand how shift registers work, we recommend reading through ["How does
 
 ## Design Guidelines
 
-The shift register output pins should act as MCU outputs in your design. All MCU inputs should remain connected directly to MCU/board pins. This is to allow the inputs to trigger "interrupts" on the MCU/board, upon which it will begin scanning the keys. Using a shift register for MCU inputs is also possible, but requires you to use a PISO shift register and will harm your battery life. Note that a [direct kscan](../../config/kscan.md#direct-gpio-driver) keyboard does not have any MCU output pins, but a diodeless keyboard is still possible by making use of a single row pin and using the [matrix kscan](../../config/kscan.md#matrix-driver) driver.
+The shift register output pins should act as MCU outputs in your design. All MCU inputs should remain connected directly to MCU/board pins. This is to allow the inputs to trigger "interrupts" on the MCU/board, upon which it will begin scanning the keys. Using a shift register for MCU inputs is also possible, but requires you to use a PISO shift register and will harm your battery life. Note that a [direct kscan](../config/kscan.md#direct-gpio-driver) keyboard does not have any MCU output pins, but a diodeless keyboard is still possible by making use of a single row pin and using the [matrix kscan](../config/kscan.md#matrix-driver) driver.
 
 :::info
 In a diode matrix, MCU output pins are those connected to the [anodes of your diodes](https://learn.sparkfun.com/tutorials/diodes/all#ideal-diodes). You most likely will need to rearrange your matrix to maximize the use of shift register output pins, in order to reduce the total number of GPIO pins connected to your MCU. For example, a 9 column 5 row `col2row` matrix could be rearranged to use 16 columns and 3 rows.
@@ -25,7 +25,7 @@ You will want to make sure that the data and clock pins of the shift register ar
 
 ZMK allows you to daisy-chain up to four shift registers. Below is a fragment of a schematic showing two shift registers that are daisy-chained.
 
-![A fragment of a schematic featuring two shift registers daisy chained together.](../../assets/hardware-integration/shift-register-daisy.png)
+![A fragment of a schematic featuring two shift registers daisy chained together.](../assets/hardware-integration/shift-register-daisy.png)
 
 ## Configuration
 

docs/docs/hardware-integration/soft-off-setup.mdx

@@ -16,7 +16,7 @@ import SidebandDirect from "./includes/_sideband-direct.md";
 import SidebandMatrix from "./includes/_sideband-matrix.md";
 import SidebandWakeupDirect from "./includes/_sideband-wakeup-direct.md";
 
-Advanced methods of adding [soft off](../../features/low-power-states.md#soft-off) to a keyboard are detailed below. The first two tabs describe methods involving hardware changes, while the last describes the firmware changes necessary to define a single specific key switch for waking up.
+Advanced methods of adding [soft off](../features/low-power-states.md#soft-off) to a keyboard are detailed below. The first two tabs describe methods involving hardware changes, while the last describes the firmware changes necessary to define a single specific key switch for waking up.
 
 <Tabs groupId="advanced-methods" queryString defaultValue="direct">
   <TabItem value="direct" label="Direct Pin"></TabItem>
@@ -68,7 +68,7 @@ Several items work together to make both triggering soft off properly, and setti
 
 ### Soft off behavior
 
-For this approach, you will need to make sure that the [soft off behavior](../../keymaps/behaviors/soft-off.md) is present in your keymap, to trigger soft off.
+For this approach, you will need to make sure that the [soft off behavior](../keymaps/behaviors/soft-off.md) is present in your keymap, to trigger soft off.
 
   </TabItem>
 </Tabs>
@@ -166,7 +166,7 @@ Finally, we will list the `wakeup_scan` device in an additional configuration se
 Here are the properties for the node:
 
 - The `compatible` property for the node must be `zmk,soft-off-wakeup-sources`.
-- The `wakeup-sources` property is a [phandle array](../devicetree.md#property-types) pointing to all the devices that should be enabled during the shutdown process to be sure they can later wake the keyboard.
+- The `wakeup-sources` property is a [phandle array](../development/devicetree.md#property-types) pointing to all the devices that should be enabled during the shutdown process to be sure they can later wake the keyboard.
 
 :::tip
 If you add your kscan to the `wakeup-sources` array, then your keyboard will wake upon pressing any key in your kscan. Essentially, this causes `&soft_off` to behave like a behavior that puts the keyboard in deep sleep. If you choose to do so, then you can omit everything aside from the `soft_off_wakers` node.

docs/docs/hardware.mdx

@@ -42,7 +42,7 @@ export const toc = [
 
 With the solid technical foundation of Zephyr™ RTOS, ZMK can support a wide diversity 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](development/hardware-integration/index.mdx#boards--shields) that have been implemented and tested by the ZMK contributors, listed below.
+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.
 
 :::note
 
@@ -61,4 +61,4 @@ Please see pages under the "Features" header in the sidebar for details.
 {/* prettier-ignore */}
 <Heading as="h2" id="contributing">Contributing</Heading>
 
-If you'd like to add support for a new keyboard shield, head over to the [New Keyboard Shield](development/hardware-integration/new-shield.mdx) documentation and note the [clean room design requirements](development/contributing/clean-room.md).
+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/docs/troubleshooting/hardware-issues.mdx

@@ -175,7 +175,7 @@ Once you have done so, you will need to adjust the `kscan` of your keyboard slig
 };
 ```
 
-could have the pin `&pro_micro 6` (D6 in the [Pro Micro pinout](../development/hardware-integration/new-shield.mdx#shield-overlays)) replaced with `&gpio0 8` (P0.08 for nRF MCUs).
+could have the pin `&pro_micro 6` (D6 in the [Pro Micro pinout](../hardware-integration/new-shield.mdx#shield-overlays)) replaced with `&gpio0 8` (P0.08 for nRF MCUs).
 
 ```dts title="<my_keyboard>.keymap"
 &kscan0 {

docs/docs/user-setup.mdx

@@ -280,7 +280,7 @@ Run `zmk keyboard add` again, and the new keyboards should appear in the list.
 
 **Create It Yourself**
 
-If nobody has created a module for your keyboard yet, or if it is your own custom design, you will need to set it up yourself. Your config repo is already set up as a module, so you can define new keyboards there. See ZMK's [new keyboard shield guide](development/hardware-integration/new-shield.mdx) for more information.
+If nobody has created a module for your keyboard yet, or if it is your own custom design, you will need to set it up yourself. Your config repo is already set up as a module, so you can define new keyboards there. See ZMK's [new keyboard shield guide](hardware-integration/new-shield.mdx) for more information.
 
 ZMK CLI can also help generate some of the boilerplate for defining a new keyboard:
 

docs/docs/zmk-cli.mdx

@@ -51,7 +51,7 @@ Run `zmk keyboard list` to print a list of supported keyboard hardware.
 
 If ZMK doesn't support your keyboard yet, you can run `zmk keyboard new` to create a new keyboard from a template.
 
-This won't walk you through all of the details of adding support for a new keyboard, but it will generate most of the boilerplate for you. See the [New Keyboard Shield](development/hardware-integration/new-shield.mdx) guide for how to finish writing the keyboard files.
+This won't walk you through all of the details of adding support for a new keyboard, but it will generate most of the boilerplate for you. See the [New Keyboard Shield](hardware-integration/new-shield.mdx) guide for how to finish writing the keyboard files.
 
 ### Module Management
 

docs/sidebars.js

@@ -141,59 +141,59 @@ module.exports = {
       ],
     },
     {
-      Development: [
+      type: "category",
+      label: "Hardware Integration",
+      link: {
+        type: "doc",
+        id: "hardware-integration/index",
+      },
+      collapsed: true,
+      items: [
+        "hardware-integration/new-board",
+        "hardware-integration/new-shield",
+        "hardware-integration/physical-layouts",
+        "hardware-integration/hardware-metadata-files",
+        "hardware-integration/pinctrl",
+        "hardware-integration/dongle",
+        "hardware-integration/shift-registers",
+        "hardware-integration/encoders",
+        "hardware-integration/soft-off-setup",
+        "hardware-integration/pointing",
+        "hardware-integration/battery",
         {
           type: "category",
-          label: "Hardware Integration",
+          label: "Bootloader",
           link: {
             type: "doc",
-            id: "development/hardware-integration/index",
+            id: "hardware-integration/bootloader/index",
           },
           collapsed: true,
           items: [
-            "development/hardware-integration/new-shield",
+            "hardware-integration/bootloader/adafruit-nrf52",
-            "development/hardware-integration/physical-layouts",
+            "hardware-integration/bootloader/tinyuf2",
-            "development/hardware-integration/hardware-metadata-files",
+            "hardware-integration/bootloader/samd21-uf2",
-            "development/hardware-integration/pinctrl",
+            "hardware-integration/bootloader/rp2",
-            "development/hardware-integration/dongle",
+            "hardware-integration/bootloader/stm32",
-            "development/hardware-integration/shift-registers",
-            "development/hardware-integration/encoders",
-            "development/hardware-integration/soft-off-setup",
-            "development/hardware-integration/pointing",
-            "development/hardware-integration/new-board",
-            "development/hardware-integration/battery",
-            {
-              type: "category",
-              label: "Bootloader",
-              link: {
-                type: "doc",
-                id: "development/hardware-integration/bootloader/index",
-              },
-              collapsed: true,
-              items: [
-                "development/hardware-integration/bootloader/adafruit-nrf52",
-                "development/hardware-integration/bootloader/tinyuf2",
-                "development/hardware-integration/bootloader/samd21-uf2",
-                "development/hardware-integration/bootloader/rp2",
-                "development/hardware-integration/bootloader/stm32",
-              ],
-            },
-            {
-              type: "category",
-              label: "Lighting",
-              link: {
-                type: "doc",
-                id: "development/hardware-integration/lighting/index",
-              },
-              collapsed: true,
-              items: [
-                "development/hardware-integration/lighting/underglow",
-                "development/hardware-integration/lighting/backlight",
-                "development/hardware-integration/lighting/led-indicators",
-              ],
-            },
           ],
         },
+        {
+          type: "category",
+          label: "Lighting",
+          link: {
+            type: "doc",
+            id: "hardware-integration/lighting/index",
+          },
+          collapsed: true,
+          items: [
+            "hardware-integration/lighting/underglow",
+            "hardware-integration/lighting/backlight",
+            "hardware-integration/lighting/led-indicators",
+          ],
+        },
+      ],
+    },
+    {
+      Development: [
         {
           type: "category",
           label: "Contributing",

docs/static/_redirects

@@ -10,17 +10,18 @@
 /docs/config/underglow /docs/config/lighting#rgb-underglow 301
 /docs/features/beta-testing /docs/features/modules#beta-testing 301
 /docs/development/setup /docs/development/local-toolchain/setup 301
-/docs/development/boards-shields-keymaps /docs/development/hardware-integration/boards-shields-keymaps 301
+/docs/development/boards-shields-keymaps /docs/hardware-integration 301
-/docs/development/hardware-metadata-files /docs/development/hardware-integration/hardware-metadata-files 301
+/docs/development/hardware-metadata-files /docs/hardware-integration/hardware-metadata-files 301
 /docs/development/clean-room /docs/development/contributing/clean-room 301
 /docs/development/documentation /docs/development/contributing/documentation 301
-/docs/development/new-shield /docs/development/hardware-integration/new-shield 301
+/docs/development/new-shield /docs/hardware-integration/new-shield 301
 /docs/development/build-flash /docs/development/local-toolchain/build-flash 301
 /docs/development/ide-integration /docs/development/local-toolchain/ide-integration 301
 /docs/development/posix-board /docs/development/local-toolchain/posix-board 301
 /docs/development/pre-commit /docs/development/local-toolchain/pre-commit 301
 /docs/development/tests /docs/development/local-toolchain/tests 301
 /docs/development/guides/new-behavior /docs/development/new-behavior 301
-/docs/development/hardware-integration/studio-setup /docs/development/hardware-integration/physical-layouts 301
+/docs/development/hardware-integration/studio-setup /docs/hardware-integration/physical-layouts 301
 /docs/keymaps/behaviors/mod-tap /docs/keymaps/behaviors/hold-tap#mod-tap
 /docs/user-setup-cli /docs/user-setup 301
+/docs/development/hardware-integration/* /docs/hardware-integration/:splat 301