refactor(docs): Document and enforce header casing conventions

ReFil · Jun 17, 2024 · 7c09eb2 · 7c09eb2
1 parent e56db30
commit 7c09eb2
Show file tree

Hide file tree

Showing 26 changed files with 63 additions and 57 deletions.
diff --git a/docs/docs/behaviors/caps-word.md b/docs/docs/behaviors/caps-word.md
@@ -21,7 +21,7 @@ Example:
 
 ### Configuration
 
-#### Continue List
+#### Continue list
 
 By default, the caps word will remain active when any alphanumeric character or underscore (`UNDERSCORE`), backspace (`BACKSPACE`), or delete (`DELETE`) characters are pressed. Any other non-modifier keycode sent will turn off caps word. If you would like to override this, you can set a new array of keys in the `continue-list` property in your keymap:
 
@@ -37,7 +37,7 @@ By default, the caps word will remain active when any alphanumeric character or
 };
 ```
 
-#### Applied Modifier(s)
+#### Applied modifier(s)
 
 In addition, if you would like _multiple_ modifiers, instead of just `MOD_LSFT`, you can override the `mods` property:
 

diff --git a/docs/docs/behaviors/hold-tap.mdx b/docs/docs/behaviors/hold-tap.mdx
@@ -35,7 +35,7 @@ When the hold-tap key is released and the hold behavior has not been triggered,
 
 ![Hold-tap comparison](../assets/hold-tap/comparison.svg)
 
-### Basic usage
+### Basic Usage
 
 For basic usage, please see the [mod-tap](mod-tap.md) and [layer-tap](layers.md#layer-tap) pages.
 

diff --git a/docs/docs/behaviors/index.mdx b/docs/docs/behaviors/index.mdx
@@ -9,7 +9,7 @@ sidebar_label: Overview
 
 Below is a summary of pre-defined behavior bindings and user-definable behaviors available in ZMK, with references to documentation pages describing them.
 
-## Key press behaviors
+## Key Press Behaviors
 
 | Binding       | Behavior                                      | Description                                                                                                                                                                                                                                       |
 | ------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -21,14 +21,14 @@ Below is a summary of pre-defined behavior bindings and user-definable behaviors
 | `&caps_word`  | [Caps Word](caps-word.md)                     | Behaves similar to caps lock, but automatically deactivates when any key not in a continue list is pressed, or if the caps word key is pressed again                                                                                              |
 | `&key_repeat` | [Key Repeat](key-repeat.md)                   | Sends again whatever keycode was last sent                                                                                                                                                                                                        |
 
-## Miscellaneous behaviors
+## Miscellaneous Behaviors
 
 | Binding  | Behavior                           | Description                                                                                                                           |
 | -------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
 | `&trans` | [Transparent](misc.md#transparent) | Passes the key press down to the next active layer in the stack for processing                                                        |
 | `&none`  | [None](misc.md#none)               | Swallows and stops the key press, no keycode will be sent nor will the key press be passed down to the next active layer in the stack |
 
-## Layer navigation behaviors
+## Layer Navigation Behaviors
 
 | Binding | Behavior                                     | Description                                                                                              |
 | ------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
@@ -38,41 +38,41 @@ Below is a summary of pre-defined behavior bindings and user-definable behaviors
 | `&tog`  | [Toggle Layer](layers.md#toggle-layer)       | Enables a layer until the layer is manually disabled                                                     |
 | `&sl`   | [Sticky Layer](sticky-layer.md)              | Activates a layer until another key is pressed, then deactivates it                                      |
 
-## Mouse emulation behaviors
+## Mouse Emulation Behaviors
 
 | Binding | Behavior                                                    | Description                     |
 | ------- | ----------------------------------------------------------- | ------------------------------- |
 | `&mkp`  | [Mouse Button Press](mouse-emulation.md#mouse-button-press) | Emulates pressing mouse buttons |
 
-## Reset behaviors
+## Reset Behaviors
 
 | Binding       | Behavior                                | Description                                                                              |
 | ------------- | --------------------------------------- | ---------------------------------------------------------------------------------------- |
 | `&sys_reset`  | [Reset](reset.md#reset)                 | Resets the keyboard and re-runs the firmware flashed to the device                       |
 | `&bootloader` | [Bootloader](reset.md#bootloader-reset) | Resets the keyboard and puts it into bootloader mode, allowing you to flash new firmware |
 
-## Output selection behaviors
+## Output Selection Behaviors
 
 | Binding | Behavior                                                 | Description                                                                                        |
 | ------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
 | `&bt`   | [Bluetooth](bluetooth.md#bluetooth-behavior)             | Completes a bluetooth action given on press, for example switching between devices                 |
 | `&out`  | [Output Selection](outputs.md#output-selection-behavior) | Allows selecting whether output is sent to the USB or bluetooth connection when both are connected |
 
-## Lighting behaviors
+## Lighting Behaviors
 
 | Binding   | Behavior                                       | Description                                                                  |
 | --------- | ---------------------------------------------- | ---------------------------------------------------------------------------- |
 | `&rgb_ug` | [RGB Underglow](underglow.md#behavior-binding) | Controls the RGB underglow, usually placed underneath the keyboard           |
 | `&bl`     | [Backlight](backlight.md#behavior-binding)     | Controls the keyboard backlighting, usually placed through or under switches |
 
-## Power management behaviors
+## Power Management Behaviors
 
 | Binding      | Behavior                                      | Description                                                     |
 | ------------ | --------------------------------------------- | --------------------------------------------------------------- |
 | `&ext_power` | [Power management](power.md#behavior-binding) | Allows enabling or disabling the VCC power output to save power |
 | `&soft_off`  | [Soft off](soft-off.md#behavior-binding)      | Turns the keyboard off.                                         |
 
-## User-defined behaviors
+## User-Defined Behaviors
 
 | Behavior                            | Description                                                                                                                                                        |
 | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

diff --git a/docs/docs/behaviors/key-repeat.md b/docs/docs/behaviors/key-repeat.md
@@ -19,7 +19,7 @@ Example:
 
 ### Configuration
 
-#### Usage Pages
+#### Usage pages
 
 By default, the key repeat will only track the last pressed key from the HID "Key" usage page, and ignore events from other usages, e.g. Consumer page.
 

diff --git a/docs/docs/behaviors/layers.md b/docs/docs/behaviors/layers.md
@@ -8,7 +8,7 @@ sidebar_label: Layers
 Often, you may want a certain key position to alter which layers are enabled, change the default layer, etc.
 Some of those behaviors are still in the works; the ones that are working now are documented here.
 
-## Defines To Refer To Layers
+## Defines to Refer to Layers
 
 When working with layers, you may have several different key positions with bindings that enable/disable those layers.
 To make it easier to refer to those layers in your key bindings, and to change which layers are where later, you can
@@ -41,7 +41,7 @@ Example:
 &mo LOWER
 ```
 
-## Layer-tap
+## Layer-Tap
 
 The "layer-tap" behavior enables a layer when a key is held, and outputs a [keypress](key-press.md) when the key is only tapped for a short time.
 

diff --git a/docs/docs/behaviors/macros.md b/docs/docs/behaviors/macros.md
@@ -223,7 +223,7 @@ Common examples are enabling one or more modifiers when the layer is active, or
 
 To achieve this, a combination of a 0ms wait time and splitting the press and release between a `&macro_pause_for_release` is used:
 
-#### Layer + Modifier
+#### Layer + modifier
 
 ```dts
 /**
@@ -256,7 +256,7 @@ lm: lm {
 };
 ```
 
-#### Layer + Underglow Color
+#### Layer + underglow color
 
 To trigger a different underglow when the macro is pressed, and when it is released, we use the macro "press" activation mode whenever triggering the `&rgb_ug` behavior:
 

diff --git a/docs/docs/behaviors/mod-morph.md b/docs/docs/behaviors/mod-morph.md
@@ -65,7 +65,7 @@ Example:
 mods = <(MOD_LGUI|MOD_LSFT|MOD_RGUI|MOD_RSFT)>;
 ```
 
-### Advanced configuration
+### Advanced Configuration
 
 `keep-mods`
 

diff --git a/docs/docs/behaviors/soft-off.md b/docs/docs/behaviors/soft-off.md
@@ -23,7 +23,7 @@ Example:
 
 ### Configuration
 
-#### Hold Time
+#### Hold time
 
 By default, the keyboard will be turned off as soon as the key bound to the behavior is released, even if the key is only tapped briefly. If you would prefer that the key need be held a certain amount of time before releasing, you can set the `hold-time-ms` to a non-zero value in your keymap:
 

diff --git a/docs/docs/behaviors/sticky-key.md b/docs/docs/behaviors/sticky-key.md
@@ -81,7 +81,7 @@ This configuration would apply to all sticky keys. This may not be appropriate i
 };
 ```
 
-### Advanced usage
+### Advanced Usage
 
 Sticky keys can be combined; if you tap `&sk LCTRL` and then `&sk LSHIFT` and then `&kp A`, the output will be ctrl+shift+a.
 

diff --git a/docs/docs/behaviors/sticky-layer.md b/docs/docs/behaviors/sticky-layer.md
@@ -36,7 +36,7 @@ You can configure a different `release-after-ms` in your keymap:
 };
 ```
 
-### Advanced usage
+### Advanced Usage
 
 Sticky layers behave slightly different from sticky keys. They are configured to `quick-release`. This means that the layer is released immediately when another key is pressed. "Normal" sticky keys are not `quick-release`; they are released when the next key is released. This makes it possible to combine sticky layers and sticky keys as such: tap `&sl 1`, tap `&sk LSHIFT` on layer 1, tap `&kp A` on base layer to output shift+A.
 

diff --git a/docs/docs/config/battery.md b/docs/docs/config/battery.md
@@ -28,7 +28,7 @@ On macOS the BLE battery reporting packets can cause the computer to wakeup from
 
 :::
 
-### Peripheral battery monitoring
+### Peripheral Battery Monitoring
 
 You can [configure ZMK to allow support for peripheral battery monitoring over BLE](system.md#split-keyboards) (e.g. when having a split keyboard with two independent and wirelessly connected sides).
 If you want to report the battery levels of both sides of a split keyboard, you should have both `CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_PROXY` and `CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_FETCHING` set to `y`.

diff --git a/docs/docs/config/encoders.md b/docs/docs/config/encoders.md
@@ -29,7 +29,7 @@ If `CONFIG_EC11` is enabled, exactly one of the following options must be set to
 
 ### Devicetree
 
-#### Keymap Sensor Config
+#### Keymap sensor config
 
 For shields/boards that export a `sensors` node configuration label, both global and per-sensor settings can be set by overriding the properties there.
 
@@ -69,7 +69,7 @@ Definition file: [zmk/app/drivers/zephyr/dts/bindings/zmk,keymap-sensors.yaml](h
 | ----------------------- | ---- | --------------------------------------------------------------- | ------- |
 | `triggers-per-rotation` | int  | Number of times to trigger the bound behavior per full rotation |         |
 
-#### EC11 Nodes
+#### EC11 nodes
 
 Applies to: `compatible = "alps,ec11"`
 

diff --git a/docs/docs/development/build-flash.mdx b/docs/docs/development/build-flash.mdx
@@ -77,7 +77,7 @@ This produces `left` and `right` subfolders under the `build` directory and two
 Build times can be significantly reduced after the initial build by omitting all build arguments except the build directory, e.g. `west build -d build/left`. The additional options and intermediate build outputs from your initial build are cached and reused for unchanged files.
 :::
 
-### Building with external modules
+### Building With External Modules
 
 ZMK supports loading additional boards, shields, code, etc. from [external Zephyr modules](https://docs.zephyrproject.org/3.5.0/develop/modules.html), facilitating out-of-tree management and versioning independent of the ZMK repository. To build with any additional modules, use the `ZMK_EXTRA_MODULES` define added to your `west build` command.
 

diff --git a/docs/docs/development/documentation.md b/docs/docs/development/documentation.md
@@ -5,7 +5,7 @@ sidebar_label: Documentation
 
 This document outlines how to test your documentation changes locally and prepare the changes for a pull request.
 
-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 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 general process for updating the ZMK documentation is:
 
@@ -52,6 +52,12 @@ The check commands can be run with the following procedure in a terminal that's
 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 - prettier and lint are unfortunately unable to do this automatically.
+:::
+
 ## Submitting a Pull Request
 
 Once the above sections are complete the documentation updates are ready to submit as a pull request.
diff --git a/docs/docs/development/ide-integration.mdx b/docs/docs/development/ide-integration.mdx
@@ -51,7 +51,7 @@ Change these options:
 
 If you are developing inside a Docker container, set the IntelliSense mode to `linux-gcc-arm` regardless of the host operating system.
 
-#### Compiler Path
+#### Compiler path
 
 Open VS Code's integrated terminal and run the following command:
 
@@ -79,7 +79,7 @@ If you are building for an platform other than ARM, replace `/arm-zephyr-eabi/bi
 /home/marvin/.local/zephyr-sdk-0.15.2/riscv64-zephyr-elf/bin/riscv64-zephyr-elf-gcc
 ```
 
-#### Compiler Commands Path
+#### Compiler commands path
 
 When building with all default options, the path to the compilation database file
 is `${workspaceFolder}/app/build/compile_commands.json` as shown in the table above,