From 74d64c7f43a9a1a0f6a0a26c981f1611ac0edaa3 Mon Sep 17 00:00:00 2001 From: Joel Challis Date: Wed, 23 Jul 2025 04:33:37 +0100 Subject: [PATCH 1/2] [docs] Align keyboard and keymap placeholders (#25509) --- docs/cli_commands.md | 14 +++++++------- docs/hardware_keyboard_guidelines.md | 10 +++++----- docs/newbs_building_firmware.md | 2 +- docs/newbs_flashing.md | 2 +- docs/reference_info_json.md | 2 +- 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/cli_commands.md b/docs/cli_commands.md index c6a7ffe1918..54bf5cc1239 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -17,12 +17,12 @@ qmk compile [-c] **Usage for Keymaps**: ``` -qmk compile [-c] [-e =] [-j ] [--compiledb] -kb -km +qmk compile [-c] [-e =] [-j ] [--compiledb] -kb -km ``` **Usage in Keyboard Directory**: -Must be in keyboard directory with a default keymap, or in keymap directory for keyboard, or supply one with `--keymap ` +Must be in keyboard directory with a default keymap, or in keymap directory for keyboard, or supply one with `--keymap ` ``` qmk compile ``` @@ -30,7 +30,7 @@ qmk compile **Usage for building all keyboards that support a specific keymap**: ``` -qmk compile -kb all -km +qmk compile -kb all -km ``` **Example**: @@ -62,7 +62,7 @@ $ qmk compile Must be under `qmk_firmware/layouts/`, and in a keymap folder. ``` -qmk compile -kb +qmk compile -kb ``` **Example**: @@ -77,11 +77,11 @@ $ qmk compile -kb dz60 It is possible to speed up compilation by adding the `-j`/`--parallel` flag. ``` -qmk compile -j -kb +qmk compile -j -kb ``` The `num_jobs` argument determines the maximum number of jobs that can be used. Setting it to zero will enable parallel compilation without limiting the maximum number of jobs. ``` -qmk compile -j 0 -kb +qmk compile -j 0 -kb ``` **Compilation Database**: @@ -120,7 +120,7 @@ qmk flash [-bl ] [-c] [-e =] [-j ] -km [-bl ] [-c] [-e =] [-j ] +qmk flash -kb -km [-bl ] [-c] [-e =] [-j ] ``` **Usage for pre-compiled firmwares**: diff --git a/docs/hardware_keyboard_guidelines.md b/docs/hardware_keyboard_guidelines.md index 7e88ff231d2..4df443f9fc3 100644 --- a/docs/hardware_keyboard_guidelines.md +++ b/docs/hardware_keyboard_guidelines.md @@ -71,8 +71,8 @@ Your keyboard should be located in `qmk_firmware/keyboards/` and the folder name * `keyboard.json` (or `info.json`) * `config.h` * `rules.mk` -* `.c` -* `.h` +* `.c` +* `.h` ### `readme.md` @@ -203,7 +203,7 @@ The `post_rules.mk` file can interpret `features` of a keyboard-level before `co See `build_keyboard.mk` and `common_features.mk` for more details. ::: -### `` +### `` This file should contain C code required for the functionality of your keyboard, for example hardware initialisation code, OLED display code, and so on. This file should only contain code necessary for the keyboard to work, and *not* things that should be left to the end user to configure in their keymap. This file is automatically included in compilation if it exists. This is not a required file. @@ -214,9 +214,9 @@ The following functions are typically defined in this file: * `bool process_record_kb(uint16_t keycode, keyrecord_t *record)` * `bool led_update_kb(led_t led_state)` -### `` +### `` -This file can contain function prototypes for custom functions and other header file code utilised by `.c`. The `.c` file should include this file. This is not a required file. +This file can contain function prototypes for custom functions and other header file code utilised by `.c`. The `.c` file should include this file. This is not a required file. ## Image/Hardware Files diff --git a/docs/newbs_building_firmware.md b/docs/newbs_building_firmware.md index f5e529b9cee..82442b7adc7 100644 --- a/docs/newbs_building_firmware.md +++ b/docs/newbs_building_firmware.md @@ -33,7 +33,7 @@ qmk new-keymap If you did not configure your environment, or you have multiple keyboards, you can specify a keyboard name: ```sh -qmk new-keymap -kb +qmk new-keymap -kb ``` Look at the output from that command, you should see something like this: diff --git a/docs/newbs_flashing.md b/docs/newbs_flashing.md index 5d5c1983e19..81319206866 100644 --- a/docs/newbs_flashing.md +++ b/docs/newbs_flashing.md @@ -60,7 +60,7 @@ open . The firmware file always follows this naming format: ``` -_.{bin,hex} +_.{bin,hex} ``` For example, the `planck/rev5` with a `default` keymap will have this filename: diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md index a64f2992b55..59daafe3f96 100644 --- a/docs/reference_info_json.md +++ b/docs/reference_info_json.md @@ -2,7 +2,7 @@ The information contained in `info.json` is combined with the `config.h` and `rules.mk` files, dynamically generating the necessary configuration for your keyboard at compile time. It is also used by the [QMK API](https://github.com/qmk/qmk_api), and contains the information [QMK Configurator](https://config.qmk.fm/) needs to display a representation of your keyboard. Its key/value pairs are ruled by the [`data/schemas/keyboard.jsonschema`](https://github.com/qmk/qmk_firmware/blob/master/data/schemas/keyboard.jsonschema) file. To learn more about the why and how of the schema file see the [Data Driven Configuration](data_driven_config) page. -You can create `info.json` files at every level under `qmk_firmware/keyboards/`. These files are combined, with more specific files overriding keys in less specific files. This means you do not need to duplicate your metadata information. For example, `qmk_firmware/keyboards/clueboard/info.json` specifies information common to all Clueboard products, such as `manufacturer` and `maintainer`, while `qmk_firmware/keyboards/clueboard/66/info.json` contains more specific information about Clueboard 66%. +You can create `info.json` files at every level under `qmk_firmware/keyboards/`. These files are combined, with more specific files overriding keys in less specific files. This means you do not need to duplicate your metadata information. For example, `qmk_firmware/keyboards/clueboard/info.json` specifies information common to all Clueboard products, such as `manufacturer` and `maintainer`, while `qmk_firmware/keyboards/clueboard/66/info.json` contains more specific information about Clueboard 66%. ## General Metadata {#general-metadata} From 36c3f4deba7e4c670736cc95db144b25156e90f1 Mon Sep 17 00:00:00 2001 From: Joel Challis Date: Wed, 23 Jul 2025 13:08:48 +0100 Subject: [PATCH 2/2] [docs] Align more keyboard placeholders (#25510) --- docs/drivers/aw20216s.md | 2 +- docs/drivers/is31fl3218.md | 2 +- docs/drivers/is31fl3236.md | 2 +- docs/drivers/is31fl3729.md | 2 +- docs/drivers/is31fl3731.md | 2 +- docs/drivers/is31fl3733.md | 2 +- docs/drivers/is31fl3736.md | 2 +- docs/drivers/is31fl3737.md | 2 +- docs/drivers/is31fl3741.md | 2 +- docs/drivers/is31fl3742a.md | 2 +- docs/drivers/is31fl3743a.md | 2 +- docs/drivers/is31fl3745.md | 2 +- docs/drivers/is31fl3746a.md | 2 +- docs/drivers/snled27351.md | 2 +- docs/getting_started_introduction.md | 4 ++-- docs/getting_started_make_guide.md | 4 ++-- docs/hardware_keyboard_guidelines.md | 4 ++-- 17 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/drivers/aw20216s.md b/docs/drivers/aw20216s.md index 042c8df1292..a8c87dd0f92 100644 --- a/docs/drivers/aw20216s.md +++ b/docs/drivers/aw20216s.md @@ -44,7 +44,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config ## LED Mapping {#led-mapping} -In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: ```c const aw20216s_led_t PROGMEM g_aw20216s_leds[AW20216S_LED_COUNT] = { diff --git a/docs/drivers/is31fl3218.md b/docs/drivers/is31fl3218.md index 1c980691204..ccc70c3340a 100644 --- a/docs/drivers/is31fl3218.md +++ b/docs/drivers/is31fl3218.md @@ -37,7 +37,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config ## LED Mapping {#led-mapping} -In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: ```c const is31fl3218_led_t PROGMEM g_is31fl3218_leds[IS31FL3218_LED_COUNT] = { diff --git a/docs/drivers/is31fl3236.md b/docs/drivers/is31fl3236.md index 98e05e4abd4..83ce2272035 100644 --- a/docs/drivers/is31fl3236.md +++ b/docs/drivers/is31fl3236.md @@ -50,7 +50,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config ## LED Mapping {#led-mapping} -In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: ```c const is31fl3236_led_t PROGMEM g_is31fl3236_leds[IS31FL3236_LED_COUNT] = { diff --git a/docs/drivers/is31fl3729.md b/docs/drivers/is31fl3729.md index 32618d82d59..1461874707d 100644 --- a/docs/drivers/is31fl3729.md +++ b/docs/drivers/is31fl3729.md @@ -120,7 +120,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config ## LED Mapping {#led-mapping} -In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: ```c const is31fl3729_led_t PROGMEM g_is31fl3729_leds[IS31FL3729_LED_COUNT] = { diff --git a/docs/drivers/is31fl3731.md b/docs/drivers/is31fl3731.md index 0d928a919ef..78b3d7b1ce7 100644 --- a/docs/drivers/is31fl3731.md +++ b/docs/drivers/is31fl3731.md @@ -61,7 +61,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config ## LED Mapping {#led-mapping} -In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: ```c const is31fl3731_led_t PROGMEM g_is31fl3731_leds[IS31FL3731_LED_COUNT] = { diff --git a/docs/drivers/is31fl3733.md b/docs/drivers/is31fl3733.md index e299f785bda..13e9148a29e 100644 --- a/docs/drivers/is31fl3733.md +++ b/docs/drivers/is31fl3733.md @@ -145,7 +145,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config ## LED Mapping {#led-mapping} -In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: ```c const is31fl3733_led_t PROGMEM g_is31fl3733_leds[IS31FL3733_LED_COUNT] = { diff --git a/docs/drivers/is31fl3736.md b/docs/drivers/is31fl3736.md index b679a232cd6..e03275531ce 100644 --- a/docs/drivers/is31fl3736.md +++ b/docs/drivers/is31fl3736.md @@ -129,7 +129,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config ## LED Mapping {#led-mapping} -In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: ```c const is31fl3736_led_t PROGMEM g_is31fl3736_leds[IS31FL3736_LED_COUNT] = { diff --git a/docs/drivers/is31fl3737.md b/docs/drivers/is31fl3737.md index d23def237ff..e4663aa0199 100644 --- a/docs/drivers/is31fl3737.md +++ b/docs/drivers/is31fl3737.md @@ -117,7 +117,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config ## LED Mapping {#led-mapping} -In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: ```c const is31fl3737_led_t PROGMEM g_is31fl3737_leds[IS31FL3737_LED_COUNT] = { diff --git a/docs/drivers/is31fl3741.md b/docs/drivers/is31fl3741.md index dce5c08b21b..b26262da7cd 100644 --- a/docs/drivers/is31fl3741.md +++ b/docs/drivers/is31fl3741.md @@ -117,7 +117,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config ## LED Mapping {#led-mapping} -In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: ```c const is31fl3741_led_t PROGMEM g_is31fl3741_leds[IS31FL3741_LED_COUNT] = { diff --git a/docs/drivers/is31fl3742a.md b/docs/drivers/is31fl3742a.md index ebe648cba44..e4f15162f69 100644 --- a/docs/drivers/is31fl3742a.md +++ b/docs/drivers/is31fl3742a.md @@ -117,7 +117,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config ## LED Mapping {#led-mapping} -In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: ```c const is31fl3742a_led_t PROGMEM g_is31fl3742a_leds[IS31FL3742A_LED_COUNT] = { diff --git a/docs/drivers/is31fl3743a.md b/docs/drivers/is31fl3743a.md index 9ca55c5eeb0..b031edd5fbf 100644 --- a/docs/drivers/is31fl3743a.md +++ b/docs/drivers/is31fl3743a.md @@ -127,7 +127,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config ## LED Mapping {#led-mapping} -In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: ```c const is31fl3743a_led_t PROGMEM g_is31fl3743a_leds[IS31FL3743A_LED_COUNT] = { diff --git a/docs/drivers/is31fl3745.md b/docs/drivers/is31fl3745.md index f13f029bfed..fb53dd36900 100644 --- a/docs/drivers/is31fl3745.md +++ b/docs/drivers/is31fl3745.md @@ -127,7 +127,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config ## LED Mapping {#led-mapping} -In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: ```c const is31fl3745_led_t PROGMEM g_is31fl3745_leds[IS31FL3745_LED_COUNT] = { diff --git a/docs/drivers/is31fl3746a.md b/docs/drivers/is31fl3746a.md index bdd5c183577..19439a8a405 100644 --- a/docs/drivers/is31fl3746a.md +++ b/docs/drivers/is31fl3746a.md @@ -132,7 +132,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config ## LED Mapping {#led-mapping} -In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: ```c const is31fl3746a_led_t PROGMEM g_is31fl3746a_leds[IS31FL3746A_LED_COUNT] = { diff --git a/docs/drivers/snled27351.md b/docs/drivers/snled27351.md index 1d91182f7c3..c0785711d9d 100644 --- a/docs/drivers/snled27351.md +++ b/docs/drivers/snled27351.md @@ -52,7 +52,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config ## LED Mapping {#led-mapping} -In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `.c`: ```c const snled27351_led_t PROGMEM g_snled27351_leds[SNLED27351_LED_COUNT] = { diff --git a/docs/getting_started_introduction.md b/docs/getting_started_introduction.md index 9417351747f..4a44e0e7005 100644 --- a/docs/getting_started_introduction.md +++ b/docs/getting_started_introduction.md @@ -19,8 +19,8 @@ Within the folder `keyboards`, its subfolder `handwired` and its vendor and manu * `config.h`: The file that sets the default compile time options. Do not edit this file directly, instead use a keymap specific `config.h`. * `info.json`: The file used for setting layout for QMK Configurator. See [Configurator Support](reference_configurator_support) for more information. * `readme.md`: A brief overview of the keyboard. -* `.h`: This file is where the keyboard layout is defined against the keyboard's switch matrix. -* `.c`: This file is where you can find custom code for the keyboard. +* `.h`: This file is where the keyboard layout is defined against the keyboard's switch matrix. +* `.c`: This file is where you can find custom code for the keyboard. For more information on project structure, see [QMK Keyboard Guidelines](hardware_keyboard_guidelines). diff --git a/docs/getting_started_make_guide.md b/docs/getting_started_make_guide.md index 59455adb30e..54f915e444c 100644 --- a/docs/getting_started_make_guide.md +++ b/docs/getting_started_make_guide.md @@ -1,8 +1,8 @@ # More Detailed `make` Instructions -The full syntax of the `make` command is `::`, where: +The full syntax of the `make` command is `::`, where: -* `` is the path of the keyboard, for example `planck` +* `` is the path of the keyboard, for example `planck` * Use `all` to compile all keyboards * Specify the path to compile a revision, for example `planck/rev4` or `planck/rev3` * If the keyboard doesn't have any folders, it can be left out diff --git a/docs/hardware_keyboard_guidelines.md b/docs/hardware_keyboard_guidelines.md index 4df443f9fc3..0b8f35a373b 100644 --- a/docs/hardware_keyboard_guidelines.md +++ b/docs/hardware_keyboard_guidelines.md @@ -203,7 +203,7 @@ The `post_rules.mk` file can interpret `features` of a keyboard-level before `co See `build_keyboard.mk` and `common_features.mk` for more details. ::: -### `` +### `.c` This file should contain C code required for the functionality of your keyboard, for example hardware initialisation code, OLED display code, and so on. This file should only contain code necessary for the keyboard to work, and *not* things that should be left to the end user to configure in their keymap. This file is automatically included in compilation if it exists. This is not a required file. @@ -214,7 +214,7 @@ The following functions are typically defined in this file: * `bool process_record_kb(uint16_t keycode, keyrecord_t *record)` * `bool led_update_kb(led_t led_state)` -### `` +### `.h` This file can contain function prototypes for custom functions and other header file code utilised by `.c`. The `.c` file should include this file. This is not a required file.