zmkfirmware · Nick-Munnich · Dec 15, 2024
@@ -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`](/docs/getting-started/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.
 - 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.
 

@@ -39,7 +39,7 @@ and should work, fine as is. However, to upgrade to the newer Docker image, you
 
 If you created your user config repository a while ago, you may find that your `build.yml` file instead references
 a `zephyr-west-action-arm` custom GitHub Action instead. In this case, the upgrade is not as direct. We suggest that
-instead you [re-create your config repository](/docs/user-setup) to get an updated setup using the new automation
+instead you [re-create your config repository](/docs/getting-started/user-setup) to get an updated setup using the new automation
 approach.
 
 :::

@@ -22,7 +22,7 @@ A future blog post will outline the complete Zephyr 3.0 changes once that work i
 
 If you created your user config repository a while ago, you may find that your `build.yml` file instead references
 a `zephyr-west-action-arm` custom GitHub Action instead. In this case, the upgrade is not as direct. We suggest that
-instead you [re-create your config repository](/docs/user-setup) to get an updated setup using the new automation
+instead you [re-create your config repository](/docs/getting-started/user-setup) to get an updated setup using the new automation
 approach.
 
 :::
@@ -40,7 +40,7 @@ Existing user config repositories using Github Actions to build will pull down Z
 
 If you created your user config repository a while ago, you may find that your `build.yml` file instead references
 a `zephyr-west-action-arm` custom GitHub Action instead. In this case, the upgrade is not as direct. We suggest that
-instead you [re-create your config repository](/docs/user-setup) to get an updated setup using the new automation
+instead you [re-create your config repository](/docs/getting-started/user-setup) to get an updated setup using the new automation
 approach.
 
 :::

@@ -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/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/getting-started/hardware) page and our
 more nuanced GH Actions automation for testing changes to ZMK.
 
 ## Coming Soon!

@@ -58,7 +58,7 @@ The day I was finally able to type on a wireless, split keyboard running ZMK was
 
 ## Onward and Upward
 
-We've come a long way since then, with our [supported hardware](/docs/hardware), [features](/docs/keymaps) and [behaviors](/docs/keymaps/behaviors/key-press) growing regularly.
+We've come a long way since then, with our [supported hardware](/docs/getting-started/hardware), [features](/docs/keymaps) and [behaviors](/docs/keymaps/behaviors/key-press) growing regularly.
 
 ZMK powered keyboards are now available in group buys and in stock at various vendors; compatible controllers have been used in a wide range of builds to empower our users to free themselves from their USB/TRRS cables and move about untethered.
 

@@ -185,7 +185,7 @@ In addition to the specific contributions listed above, various improvements and
 
 #### Reusable GitHub build workflow
 
-[elagil](https://github.com/elagil) helped switch the build workflow used by the [user config repos](/docs/user-setup) to a reusable one in [#1183](https://github.com/zmkfirmware/zmk/pull/1183) and it was further tweaked by [filterpaper] in [#1258](https://github.com/zmkfirmware/zmk/pull/1258). This allows any changes in the workflow to be propagated automatically to users, rather than requiring them to make the updates. The build workflow can be customized by the users [using input parameters](https://github.com/zmkfirmware/zmk/blob/main/.github/workflows/build-user-config.yml#L5) if desired.
+[elagil](https://github.com/elagil) helped switch the build workflow used by the [user config repos](/docs/getting-started/user-setup) to a reusable one in [#1183](https://github.com/zmkfirmware/zmk/pull/1183) and it was further tweaked by [filterpaper] in [#1258](https://github.com/zmkfirmware/zmk/pull/1258). This allows any changes in the workflow to be propagated automatically to users, rather than requiring them to make the updates. The build workflow can be customized by the users [using input parameters](https://github.com/zmkfirmware/zmk/blob/main/.github/workflows/build-user-config.yml#L5) if desired.
 
 #### Pre-commit hooks
 

@@ -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](/docs/getting-started/user-setup#user-config-setup-script), except without downloading a single thing.
 
 ### User Config Setup in Browser
 

@@ -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](../../getting-started/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](../../getting-started/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
@@ -66,7 +66,7 @@ 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](../../getting-started/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/arm/planck) board directory.
 
 With this type of keyboard, the full ZMK definition for the keyboard exists in the `<board_root>/boards/<arch>/<keyboard_name>` directory where `<board_root>` is `zmk/app` or a [module](../../features/modules.mdx) root, e.g. `zmk/app/boards/arm/planck/`.
@@ -118,7 +118,7 @@ Also see the [new keyboard shield guide](new-shield.mdx#shield-overlays) for inf
 </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](../../getting-started/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/`.

@@ -100,7 +100,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](../../getting-started/hardware.mdx) in order to copy and modify as a starting point.
 :::
 
 There are two required [Kconfig](https://docs.zephyrproject.org/3.5.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`.
@@ -549,7 +549,7 @@ If you wish to test that your keyboard works with [ZMK Studio](../../features/st
 ### 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`](../../getting-started/customisation/index.md) 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).

@@ -160,7 +160,7 @@ west build -b nice_nano_v2 -- -DSHIELD=vendor_shield -DZMK_EXTRA_MODULES="C:/Use
 ### 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](../../getting-started/user-setup.mdx#github-repo)
 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.**

@@ -110,7 +110,7 @@ zephyr_udc0: &usbd {
 
 Previously, enabling logging required setting the `CONFIG_ZMK_USB_LOGGING` Kconfig symbol. If for whatever reason
 a custom board definition does not support the new `zmk-usb-logging` snippet, you can try setting this symbol at the keyboard level, typically in the `config/<your_keyboard>.conf`
-file if you are using a [user config repository](user-setup.mdx). It can also be enabled at the ZMK level using the `app/prj.conf` file, or other
+file if you are using a [user config repository](../getting-started/user-setup.mdx). It can also be enabled at the ZMK level using the `app/prj.conf` file, or other
 search locations described in the [configuration overview](config/index.md#config-file-locations).
 
 :::note

@@ -25,7 +25,7 @@ The shift to using modules for keyboards is a relatively recent one, and not all
 
 ### GitHub Actions
 
-When [using GitHub Actions to build ZMK](../user-setup.mdx), adding modules is as simple as modifying the `west.yml` found in your `zmk-config`'s `config` directory. The recommended way of doing so is:
+When [using GitHub Actions to build ZMK](../getting-started/user-setup.mdx), adding modules is as simple as modifying the `west.yml` found in your `zmk-config`'s `config` directory. The recommended way of doing so is:
 
 1. Find the URL base (the parent URL) for the module and add it as an entry to the [remotes](https://docs.zephyrproject.org/3.5.0/develop/west/manifest.html#remotes).
 2. Add the module as an entry to the [projects](https://docs.zephyrproject.org/3.5.0/develop/west/manifest.html#projects).
@@ -141,7 +141,7 @@ branch and create the pull request.
 
 ### GitHub Actions
 
-When [using GitHub Actions to build ZMK](../user-setup.mdx), once you have obtained the correct URL, you'll need to modify the `west.yml` file similarly to [Building With Modules](#building-with-modules). Add the remote for the branch like in said section. The difference is that you will need to change the selected remote and revision (or branch) for the `zmk` project.
+When [using GitHub Actions to build ZMK](../getting-started/user-setup.mdx), once you have obtained the correct URL, you'll need to modify the `west.yml` file similarly to [Building With Modules](#building-with-modules). Add the remote for the branch like in said section. The difference is that you will need to change the selected remote and revision (or branch) for the `zmk` project.
 
 #### Example
 

@@ -42,7 +42,7 @@ For the currently used BLE-based transport, split communication increases the av
 ## Building and Flashing Firmware
 
 ZMK split keyboards require building and flashing different firmware files for each split part.
-For instance when [using the GitHub workflow](../user-setup.mdx) to build two part split keyboards, two firmware files that typically contain `<keyboard>_left` and `<keyboard>_right` in the file names will be produced.
+For instance when [using the GitHub workflow](../getting-started/user-setup.mdx) to build two part split keyboards, two firmware files that typically contain `<keyboard>_left` and `<keyboard>_right` in the file names will be produced.
 These files need to be flashed to the respective controllers of the two halves.
 
 :::tip[Updating your keymap]