docs: reduce the use of admonitions (#3371)

* docs: reduce use of admonitions

- Removed some admonitions
- Some are merged with surrounding paragraphs
- Also slipped in a bit of other formatting changes

* address review comments

* address review comments

docs/docs/config/encoders.md

@@ -55,12 +55,8 @@ Per sensor overrides can be added with ordered nested nodes with the correct ove
 };
 ```
 
-:::note
-
 The names of the child nodes are not important, and are applied in order to the sensors listed in the `sensors` property of the sensors node.
 
-:::
-
 Applies to the node and child nodes of: `compatible = "zmk,keymap-sensors"`
 
 Definition file: [zmk/app/drivers/zephyr/dts/bindings/zmk,keymap-sensors.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/drivers/zephyr/dts/bindings/zmk%2Ckeymap-sensors.yaml)

docs/docs/development/contributing/documentation.md

@@ -11,6 +11,8 @@ This document outlines how to test your documentation changes locally and prepar
 
 The documentation is written with [Docusaurus](https://docusaurus.io/). The ZMK source code has all of the necessary Docusaurus dependencies included, but referencing their documentation can be helpful at times.
 
+The website is built using the latest LTS version of node, which is available at <https://nodejs.org/en/download/>.
+
 The general process for updating the ZMK documentation is:
 
 1. Update the documentation
@@ -18,14 +20,6 @@ The general process for updating the ZMK documentation is:
 3. Ensure the sources are formatted properly and linted
 4. Create a Pull Request for review and inclusion into the ZMK sources
 
-:::note
-If you are working with the documentation from within VS Code+Docker please be aware the documentation will not be auto-generated when making changes while the server is running. You'll need to restart the server when saving changes to the documentation.
-:::
-
-:::note
-You will need `Node.js` and `npm` installed to update the documentation. If you're using the ZMK dev container (Docker) the necessary dependencies are already installed. Otherwise, you must install these dependencies yourself. Since `Node.js` packages in Linux distributions tend to be outdated, it's recommended to install the current version from a repository like [NodeSource](https://github.com/nodesource/distributions) to avoid build errors.
-:::
-
 ## Testing Documentation Updates Locally
 
 To verify documentation updates locally, follow the following procedure. The `npm` commands and first step will need to be run from a terminal.
@@ -52,15 +46,9 @@ The check commands can be run with the following procedure in a terminal that's
 3. Run `npm run lint`
 4. Run `npm run build`
 
-:::danger
 If any of the above steps throw an error, they need to be addressed and all of the checks re-run prior to submitting a pull request.
-:::
 
-:::note
+The documentation uses American English spelling and grammar conventions. Title case is used for the first three heading levels, with sentence case used beyond that. Please make sure your changes conform to these conventions.
-The documentation uses American English spelling and grammar conventions. Title case is used for the first three heading levels, with sentence case used beyond that.
-
-Please make sure your changes conform to these conventions - prettier and lint are unfortunately unable to do this automatically.
-:::
 
 ## Submitting a Pull Request
 

docs/docs/development/module-creation.md

@@ -12,9 +12,7 @@ sidebar_label: ZMK Module Creation
 
 See also Zephyr's [page on modules](https://docs.zephyrproject.org/4.1.0/develop/modules.html).
 
-:::tip
+For open source hardware designs, it's recommended to **not** include the hardware design files in the ZMK module itself, since the module will be fetched by users during build and having design files in the module would likely make the module unnecessarily large and slow to fetch.
-For open source hardware designs, it can be convenient to use [Git submodules](https://github.blog/open-source/git/working-with-submodules/) to have the ZMK module also be a Git submodule of the repository hosting the hardware design.
-:::
 
 ## Module Setup
 
@@ -133,15 +131,15 @@ Note that the `include` and `src` folders are not mandated by the module system,
 Modules should expose all provided header files with an include path name beginning with the module-name, for example at `include/zmk_<type>_<description>/<header>.h`.
 
 :::info
-If your module requires adding drivers to existing subsystems in modules, you will need to use the `zephyr_library_amend()` CMake command, which requires you to have a specific directory structure. See [here](https://github.com/zephyrproject-rtos/zephyr/blob/main/cmake/modules/extensions.cmake#L454) for the definition and some documentation in the comments, with an example [here](https://github.com/petejohanson/ec-support-zmk-module/tree/main/drivers/kscan).
+If your module requires adding drivers to existing subsystems in modules, you will need to use the `zephyr_library_amend()` CMake command, which requires you to have a specific directory structure. See [`zephyr/cmake/modules/extensions.cmake`](https://github.com/zephyrproject-rtos/zephyr/blob/main@%7B2025-Feb-15%7D/cmake/modules/extensions.cmake#L492) for the definition and some documentation in the comments, with an example in [`petejohanson/ec-support-zmk-module`](https://github.com/petejohanson/ec-support-zmk-module/tree/main/drivers/kscan).
 :::
 
 ## Examples
 
 Below are some examples of modules for different types. Unless under the `zmkfirmware` project, these are not endorsed officially and may not follow our conventions perfectly. For such reason, the modules chosen to be presented here may change with time.
 
-- Keyboard: https://github.com/petejohanson/zmk-keyboards-katori
+- Keyboard: <https://github.com/petejohanson/zmk-keyboards-katori>
-- Behavior: https://github.com/urob/zmk-leader-key
+- Behavior: <https://github.com/urob/zmk-leader-key>
-- Driver: https://github.com/petejohanson/cirque-input-module
+- Driver: <https://github.com/petejohanson/cirque-input-module>
-- Feature: https://github.com/joelspadin/zmk-locales
+- Feature: <https://github.com/joelspadin/zmk-locales>
-- VFX: https://github.com/caksoylar/zmk-rgbled-widget
+- VFX: <https://github.com/caksoylar/zmk-rgbled-widget>

docs/docs/features/led-indicators.md

@@ -54,14 +54,10 @@ For example, if you want the LED to be off when the indicator is active, 100% br
 };
 ```
 
-:::note
-
 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](../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](../hardware-integration/lighting/led-indicators.md) for instructions to enable this feature on a keyboard.

docs/docs/features/lighting.md

@@ -11,7 +11,7 @@ Your keyboard likely uses only one type, depending on the type of LED hardware i
 - [Backlight](#backlight) system controls parallel-connected, non-addressable, single color LEDs.
   These are found on keyboards that have a single color backlight that only allows for brightness control.
 
-:::warning
+:::info
 
 Although the naming of the systems might imply it, which system you use typically does _not_ depend on the physical location of the LEDs.
 Instead, you should use the one that supports the LED hardware type that your keyboard has, as described above.

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

@@ -44,13 +44,9 @@ It is recommended to add the `wakeup-source` property to `kscan` devices even if
 
 The soft off feature is used to turn the keyboard on and off explicitly, rather than through a timeout like the deep sleep feature. Depending on the keyboard, this may be through a dedicated on/off push button defined in hardware, or merely through an additional binding in the keymap to turn the device off and an existing reset button to turn the device back on.
 
-The feature is intended as an alternative to using a hardware switch to physically cut power from the battery to the keyboard. This can be useful for existing PCBs not designed for wireless that don't have a power switch, or for new designs that favor a push button on/off like found on other devices. It yields power savings comparable to the deep sleep state.
-
-:::note
-
 The device enters the same software power-off state as in deep sleep, but is significantly more restrictive in the sources which can wake it. Power is _not_ technically removed from the entire system, unlike a hardware switch.
 
-:::
+The feature is intended as an alternative to using a hardware switch to physically cut power from the battery to the keyboard. This can be useful for existing PCBs not designed for wireless that don't have a power switch, or for new designs that favor a push button on/off like found on other devices. It yields power savings comparable to the deep sleep state.
 
 A device can be put in the soft off state by:
 

docs/docs/features/studio.md

@@ -6,7 +6,7 @@ ZMK Studio provides runtime update functionality to ZMK powered devices, allowin
 
 :::info
 
-To use ZMK Studio, a keyboard needs to be [configured appropriately](#adding-zmk-studio-support-to-a-keyboard). ZMK has updated some, but not all, of its in-tree keyboards for use with ZMK Studio, the list of which can be found [here](/blog/2024/11/11/zmk-studio-mvp-ga). If your keyboard is supported by an external module/config, check with the maintainer to see if support has been added.
+To use ZMK Studio, a keyboard needs to be [configured appropriately](#adding-zmk-studio-support-to-a-keyboard). ZMK has updated some, but not all, of its in-tree keyboards for use with ZMK Studio, the list of which can be found in the [ZMK Studio blog post](/blog/2024/11/11/zmk-studio-mvp-ga). If your keyboard is supported by an external module/config, check with the maintainer to see if support has been added.
 
 :::
 
@@ -54,7 +54,7 @@ Generally, if you intend to use ZMK Studio, then you should not make any further
 
 ## Accessing ZMK Studio
 
-You can use ZMK Studio with Chrome/Edge at https://zmk.studio/.
+You can use ZMK Studio with Chrome/Edge at <https://zmk.studio/>.
 
 To use the native app for Linux, macOS, or Windows, visit the [download page](https://zmk.studio/download).
 

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

@@ -15,12 +15,10 @@ For example: the `kyria` shield has a [`boards/nice_nano_nrf52840_zmk.overlay`](
 
 ### nRF52-Based Boards
 
-Using an SPI-based LED strip driver on the `&spi3` interface is the simplest option for nRF52-based boards. If possible, avoid using pins which are limited to low-frequency I/O for this purpose. The resulting interference may result in poor wireless performance.
+Using an SPI-based LED strip driver on the `&spi3` interface is the simplest option for nRF52-based boards.
 
 :::info
-
+If possible, avoid using pins which are limited to low-frequency I/O for this purpose. The resulting interference may result in poor wireless performance. The list of low frequency I/O pins for the nRF52840 can be found at <https://docs.nordicsemi.com/bundle/ps_nrf52840/page/pin.html>.
-The list of low frequency I/O pins for the nRF52840 can be found [here](https://docs.nordicsemi.com/bundle/ps_nrf52840/page/pin.html).
-
 :::
 
 The following example uses `P0.06` as the "Data In" pin of a WS2812-compatible LED strip:
@@ -69,13 +67,9 @@ The following example uses `P0.06` as the "Data In" pin of a WS2812-compatible L
 };
 ```
 
-:::note
-
 Standard WS2812 LEDs use a wire protocol where the bits for the colors green, red, and blue values are sent in that order.
 If your board/shield uses LEDs that require the data sent in a different order, the `color-mapping` property ordering should be changed to match.
 
-:::
-
 ### Other Boards
 
 Be sure to check the Zephyr documentation for the LED strip and necessary hardware bindings. Not every board has an `spi3` node, or configures `pinctrl` the same way. Reconcile this with any hardware restrictions found in the manufacturer's datasheet. Additional hardware interfaces may need to be enabled via Kconfig.

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

@@ -32,7 +32,7 @@ This guide assumes you already have a configured GitHub account. If you don't ye
 
 Follow these steps to create your new repository:
 
-- Visit https://github.com/zmkfirmware/unified-zmk-config-template
+- Visit <https://github.com/zmkfirmware/unified-zmk-config-template>
 - Click the green "Use this template" button
 - In the drop down that opens, click "Use this template".
 - In the following screen, provide the following information:

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

@@ -62,11 +62,7 @@ A key description has the shape `<&key_physical_attrs w h x y r rx ry>` with the
 
 You can specify negative values in devicetree using parentheses around it, e.g. `(-3000)` for a 30 degree counterclockwise rotation.
 
-:::tip
+We recommend the use of <https://zmk-physical-layout-converter.streamlit.app> for writing a physical layout or converting one from a QMK JSON definition. If your keyboard already has a physical layout defined for the use with KLE, we recommend using <https://nickcoutsos.github.io/keymap-layout-tools/> first to convert your existing layout into QMK JSON. The second tool can also import the position data from KiCAD, if said program was used to design the keyboard.
-
-We recommend the use of [this tool](https://zmk-physical-layout-converter.streamlit.app/) for writing a physical layout or converting one from a QMK JSON definition. If your keyboard already has a physical layout defined for the use with KLE, we recommend using [this other tool](https://nickcoutsos.github.io/keymap-layout-tools/) first to convert your existing layout into QMK JSON. The second tool can also import the position data from KiCAD, if said program was used to design the keyboard.
-
-:::
 
 ### Physical Layout with Keys Example
 
@@ -207,11 +203,7 @@ The position map should be marked as `complete` if all desired binding transfers
 
 See also the [configuration section on position maps](../config/layout.md#physical-layout-position-map).
 
-:::tip
+We recommend the use of <https://zmk-layout-helper.netlify.app>, distinct from the previous two mentioned, for the purposes of writing a position map.
-
-We recommend the use of [this tool](https://zmk-layout-helper.netlify.app/), distinct from the previous two mentioned, for the purposes of writing a position map.
-
-:::
 
 #### Writing a position map
 

docs/docs/hardware-integration/pinctrl.mdx

@@ -8,15 +8,11 @@ import TabItem from "@theme/TabItem";
 import InterconnectTabs from "@site/src/components/interconnect-tabs";
 import Metadata from "@site/src/data/hardware-metadata.json";
 
-:::info
 This page exists to provide a guide to [Pin Control](https://docs.zephyrproject.org/4.1.0/hardware/pinctrl/index.html#pin-control) for ZMK users and designers. Refer to [Zephyr's page on Pin Control](https://docs.zephyrproject.org/4.1.0/hardware/pinctrl/index.html#pin-control) for elaboration and more details on any of the points raised here.
-:::
 
 A basic keyboard design as introduced in the [new shield guide](./new-shield.mdx) only uses its pins for the keyboard matrix. Many keyboard designs make use of advanced components or functionality, such as displays or shift registers. This results in the keyboard making use of communication protocols such as (but not limited to) SPI, I2C, or UART. Configuring pins for the usage of advanced functionality such as drivers for the previously named protocols is referred to as "Pin Control".
 
-:::warning
 The details of pin control can vary from vendor to vendor. An attempt was made to be as general as possible, but it isn't possible to cover all possible cases. The approaches for the nRF52840 and RP2040 MCUs/SoCs are documented in their entirety below. For other MCUs/SoCs, please refer to the [Zephyr documentation](https://docs.zephyrproject.org/4.1.0/index.html) and the examples and other files found in-tree of [ZMK](https://github.com/zmkfirmware/zmk/tree/main/app/boards) and [ZMK's fork of Zephyr](https://github.com/zmkfirmware/zephyr).
-:::
 
 ## Boards, Shields, and Modules
 
@@ -33,10 +29,8 @@ Pin control is always defined for a _board_, never for a shield:
   ```
   Note that you will need to define a separate overlay _for each_ of the boards to be used with the shield.
 
-:::info
 Assume that the shield that you are using is found in-tree of ZMK or within an external module, and _does not_ contain the overlay for the board that you wish to use.
 If this is the case, then you should fork the source repository and add the overlay to the fork. Use said fork to build your firmware, and potentially submit a PR to upstream.
-:::
 
 ## Predefined Nodes
 

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

@@ -9,9 +9,7 @@ Shift registers are the recommended method of adding additional GPIO pins to MCU
 This page assumes that you are using a SIPO shift register with the part number 74HC595. Other shift registers can work as well but this is the most commonly used one.
 :::
 
-:::tip
 To understand how shift registers work, we recommend reading through ["How does the 74HC595 Shift Register work?"](https://lastminuteengineers.com/74hc595-shift-register-arduino-tutorial/#how-does-the-74hc595-shift-register-work).
-:::
 
 ## Design Guidelines
 

docs/docs/keymaps/behaviors/hold-tap.mdx

@@ -372,11 +372,9 @@ Including `hold-trigger-key-positions` in your hold-tap definition turns on the
 
 In all other situations, positional hold-tap will not modify the behavior of your hold-tap. Positional hold-tap is useful when used with home-row modifiers: for example, if you have a home-row modifier key in the left hand, by including only key positions from the right hand in `hold-trigger-key-positions`, you will only get hold behaviors during cross-hand key combinations unless you exceed `tapping-term-ms` when using "balanced" or "hold-preferred" flavors.
 
-For home-row mods, it is recommended to use this property with `hold-trigger-on-release` so that modifiers on the same hand can be combined.
-
-:::info
 `hold-trigger-key-positions` is an array of key position indexes. Key positions are numbered sequentially according to your keymap, starting with 0. So if the first key in your keymap is Q, this key is in position 0. The next key (probably W) will be in position 1, et cetera.
-:::
+
+For home-row mods, it is recommended to use this property with `hold-trigger-on-release` so that modifiers on the same hand can be combined.
 
 <details>
     <summary>The following example uses a hold-tap behavior definition configured with the `hold-preferred` flavor, and with positional hold-tap enabled:</summary>

docs/docs/keymaps/behaviors/macros.md

@@ -312,10 +312,6 @@ To avoid repetition or possible typos when declaring a **zero parameter macro**,
     )
 ```
 
-:::note
-`ZMK_MACRO()` **only supports declaring non-parameterized (zero parameter) macros**; parameterized declarations are not currently supported.
-:::
-
 This can be used instead of a complete macro definition. During the firmware build process, the example above would produce the complete macro definition below:
 
 ```dts

docs/docs/keymaps/behaviors/power.md

@@ -48,7 +48,7 @@ The on/off state that is set by the `&ext_power` behavior will be [saved to flas
 However it will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE`](../../config/system.md#general) milliseconds in order to reduce potential wear on the flash memory.
 :::
 
-### Example:
+### Examples
 
 1. Behavior binding to enable the external power
 

docs/docs/keymaps/input-processors/behaviors.md

@@ -7,12 +7,8 @@ sidebar_label: Behaviors
 
 The behaviors input processor is used invoke standard behaviors when certain input events occur; most frequently this is used to trigger behaviors when certain mouse buttons are triggered by physical pointing devices.
 
-:::note
-
 This input processor is primarily intended for `INPUT_EV_KEY` type of events that have a binary on/off state, not vector types for relative or absolute movements.
 
-:::
-
 :::note[Source-specific behaviors on split keyboards]
 Invoking a [source-specific behavior](../../features/split-keyboards.md#source-locality-behaviors) such as one of the [reset behaviors](../behaviors/reset.md) using this input processor will always trigger it on the central side of the keyboard, regardless of the side includes the input device that originally generated the input event.
 :::

docs/docs/keymaps/list-of-keycodes.mdx

@@ -9,11 +9,6 @@ import Table from "@site/src/components/codes/Table";
 
 This is the reference page for keycodes used by behaviors. Use the table of contents (on the right or the top) for easy navigation.
 
-:::warning
-Take extra notice of the spelling of the keycodes, especially the shorthand spelling.
-Otherwise, it will result in an elusive parsing error!
-:::
-
 :::info[Keyboard vs. Consumer keycodes]
 In the below tables, there are keycode pairs with similar names where one variant has a `K_` prefix and another `C_`.
 These variants correspond to similarly named usages from different [HID usage pages](https://usb.org/sites/default/files/hut1_2.pdf#page=16),

docs/docs/troubleshooting/building-issues.md

@@ -53,12 +53,10 @@ A `devicetree_generated.h` error that follows with an "undeclared here" string i
 
 In this example, the error string `DT_N_S_keymap_S_symbol_layer_P_bindings_IDX_12_PH_P_label` indicates a problem with the key binding in position `12` in the `symbol_layer` of the keymap.
 
-:::info
 Key positions are numbered starting from `0` at the top left key on the keymap, incrementing horizontally, row by row.
-:::
 
 :::tip
-A common mistake that leads to this error is to use [key press keycodes](keymaps/behaviors/key-press.md) without the leading `&kp` binding. That is, having entries such as `SPACE` that should have been `&kp SPACE`.
+A common mistake that leads to this error is to use [key press keycodes](keymaps/behaviors/key-press.md) without the leading `&kp` binding. That is, having entries such as `&kp A SPACE &kp B` that should have been `&kp A &kp SPACE &kp B`.
 :::
 
 ## Diagnosing Unexpected Build Results