From 65667b863ad380955da60d38ac2ae81b4dab06f5 Mon Sep 17 00:00:00 2001 From: Joel Spadin Date: Fri, 6 Oct 2023 22:05:49 -0500 Subject: [PATCH] docs: Add syntax highlighting to more code blocks Added language tags to more code blocks in the documentation to enable syntax highlighting. --- docs/README.md | 6 ++-- docs/blog/2020-10-03-bootloader-fix.md | 6 ++-- docs/blog/2020-11-09-zmk-sotf-3.md | 4 +-- docs/blog/2021-01-27-zmk-sotf-4.md | 8 ++--- docs/blog/2022-04-02-zephyr-3-0.md | 26 +++++++------- docs/blog/2022-04-10-zmk-sotf-5.md | 10 +++--- docs/blog/2023-04-06-zephyr-3-2.md | 30 ++++++++-------- docs/blog/2023-06-18-encoder-refactors.md | 10 +++--- docs/docs/behaviors/backlight.md | 6 ++-- docs/docs/behaviors/bluetooth.md | 10 +++--- docs/docs/behaviors/caps-word.md | 8 ++--- docs/docs/behaviors/hold-tap.md | 18 +++++----- docs/docs/behaviors/key-press.md | 4 +-- docs/docs/behaviors/key-repeat.md | 4 +-- docs/docs/behaviors/key-toggle.md | 2 +- docs/docs/behaviors/layers.md | 14 ++++---- docs/docs/behaviors/macros.md | 26 +++++++------- docs/docs/behaviors/misc.md | 4 +-- docs/docs/behaviors/mod-morph.md | 8 ++--- docs/docs/behaviors/mod-tap.md | 4 +-- docs/docs/behaviors/outputs.md | 8 ++--- docs/docs/behaviors/power.md | 8 ++--- docs/docs/behaviors/reset.md | 4 +-- docs/docs/behaviors/sensor-rotate.md | 4 +-- docs/docs/behaviors/sticky-key.md | 8 ++--- docs/docs/behaviors/sticky-layer.md | 4 +-- docs/docs/behaviors/tap-dance.md | 4 +-- docs/docs/behaviors/underglow.md | 6 ++-- docs/docs/config/index.md | 16 ++++----- docs/docs/config/kscan.md | 12 +++---- docs/docs/customization.md | 4 +-- docs/docs/development/build-flash.md | 10 +++--- docs/docs/development/ide-integration.md | 2 +- docs/docs/development/new-behavior.md | 4 +-- docs/docs/development/new-shield.md | 44 ++++++++++------------- docs/docs/development/posix-board.md | 4 +-- docs/docs/development/usb-logging.md | 6 ++-- docs/docs/features/backlight.md | 24 ++++++------- docs/docs/features/battery.md | 2 +- docs/docs/features/beta-testing.md | 6 ++-- docs/docs/features/bluetooth.md | 4 +-- docs/docs/features/combos.md | 2 +- docs/docs/features/conditional-layers.md | 2 +- docs/docs/features/debouncing.md | 4 +-- docs/docs/features/encoders.md | 4 +-- docs/docs/features/keymaps.md | 10 +++--- docs/docs/features/underglow.md | 12 +++---- docs/docs/keymap-example-file.md | 2 +- docs/docs/keymap-example.md | 2 +- docs/docs/user-setup.md | 6 ++-- 50 files changed, 215 insertions(+), 221 deletions(-) diff --git a/docs/README.md b/docs/README.md index fab8b874..1fd6775d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,13 +8,13 @@ The ZMK Documentation is licensed [CC-BY-NC-SA](http://creativecommons.org/licen ### Installation -``` +```sh $ npm ci ``` ### Local Development -``` +```sh $ npm start ``` @@ -22,7 +22,7 @@ This command starts a local development server and open up a browser window. Mos ### Build -``` +```sh $ npm build ``` diff --git a/docs/blog/2020-10-03-bootloader-fix.md b/docs/blog/2020-10-03-bootloader-fix.md index ec1d7b0b..435034cf 100644 --- a/docs/blog/2020-10-03-bootloader-fix.md +++ b/docs/blog/2020-10-03-bootloader-fix.md @@ -77,7 +77,7 @@ So first I enabled logging of the NVS module by adding `CONFIG_NVS_LOG_LEVEL_DBG=y` to my `.conf` file. I repeated the same test of spamming RGB underglow effect cycle and the resulting logs I got were this: -``` +```log [00:00:00.000,671] fs_nvs: 8 Sectors of 4096 bytes [00:00:00.000,671] fs_nvs: alloc wra: 3, f70 [00:00:00.000,671] fs_nvs: data wra: 3, f40 @@ -130,7 +130,7 @@ and [Dan Halbert](https://github.com/dhalbert) pointed me towards the [linker map](https://github.com/adafruit/Adafruit_nRF52_Bootloader/blob/master/linker/nrf52840.ld) of the nRF52840. Let's take a look. -``` +```linker-script FLASH (rx) : ORIGIN = 0xF4000, LENGTH = 0xFE000-0xF4000-2048 /* 38 KB */ BOOTLOADER_CONFIG (r): ORIGIN = 0xFE000 - 2048, LENGTH = 2048 @@ -166,7 +166,7 @@ Now that we've found the issue, we can pretty easily fix this. We'll need to move the settings flash area back so that it doesn't overlap with the bootloader. First we calculate the size of the of flash area the bootloader is using. -``` +```linker-script 0x100000 (end of flash) - 0x0F4000 (start of bootloader) = 0xC000 (48KB) ``` diff --git a/docs/blog/2020-11-09-zmk-sotf-3.md b/docs/blog/2020-11-09-zmk-sotf-3.md index 9e250a99..11d67040 100644 --- a/docs/blog/2020-11-09-zmk-sotf-3.md +++ b/docs/blog/2020-11-09-zmk-sotf-3.md @@ -30,7 +30,7 @@ This also laid the foundation for the other keymap related changes that are now [okke-formsma] added the ability to apply modifiers to a code, e.g.: -``` +```dts &kp LC(C) ``` @@ -63,7 +63,7 @@ and nice!nano that have specialized hardware for this purpose. With this change, you can add -``` +```dts &ext_power EP_TOG ``` diff --git a/docs/blog/2021-01-27-zmk-sotf-4.md b/docs/blog/2021-01-27-zmk-sotf-4.md index e7ff3232..fbb53e40 100644 --- a/docs/blog/2021-01-27-zmk-sotf-4.md +++ b/docs/blog/2021-01-27-zmk-sotf-4.md @@ -25,7 +25,7 @@ The initial [combos](/docs/features/combos) work has landed! The amazing [okke-f An example, that would send the `ESC` keycode when pressing both the first and second positions on your keyboard: -``` +```dts / { combos { compatible = "zmk,combos"; @@ -46,13 +46,13 @@ Combos currently are "global", and not scoped to a given active layer. There is [okke-formsma] also contributed the initial "sticky keys" behavior, which can be used for functionality sometimes called "one shot mods" or "one shot layers". In your keymap, this would like like: -``` +```dts &sk LEFT_CONTROL ``` for a sticky key/modifier, or: -``` +```dts &sl NAV ``` @@ -68,7 +68,7 @@ This is most frequently used when using multiple core base layers with different [okke-formsma] added an implementation of the "Grave Escape" behavior, developing a more generic "mod-morph" behavior to do so. Adding -``` +```dts &gresc ``` diff --git a/docs/blog/2022-04-02-zephyr-3-0.md b/docs/blog/2022-04-02-zephyr-3-0.md index 103573c6..6ec4c904 100644 --- a/docs/blog/2022-04-02-zephyr-3-0.md +++ b/docs/blog/2022-04-02-zephyr-3-0.md @@ -29,12 +29,12 @@ Existing user config repositories using Github Actions to build will pull down Z - Change `zmkfirmware/zmk-build-arm:2.5` to `zmkfirmware/zmk-build-arm:stable` wherever it is found - Locate and delete the lines for the DTS output step, which is no longer needed: - ``` - - name: ${{ steps.variables.outputs.display-name }} DTS File - if: ${{ always() }} - run: | - if [ -f "build/zephyr/${{ matrix.board }}.pre.tmp" ]; then cat -n build/zephyr/${{ matrix.board }}.pre.tmp; fi - if [ -f "build/zephyr/zephyr.dts" ]; then cat -n build/zephyr/zephyr.dts; fi + ```yaml + - name: ${{ steps.variables.outputs.display-name }} DTS File + if: ${{ always() }} + run: | + if [ -f "build/zephyr/${{ matrix.board }}.pre.tmp" ]; then cat -n build/zephyr/${{ matrix.board }}.pre.tmp; fi + if [ -f "build/zephyr/zephyr.dts" ]; then cat -n build/zephyr/zephyr.dts; fi ``` :::note @@ -76,7 +76,7 @@ The following changes have [already been completed](https://github.com/zmkfirmwa Zephyr's WS2812 `led_strip` driver added a new required property. When adding [underglow](/docs/features/underglow#adding-rgb-underglow-to-a-board) to a board, you now must also add the additional include `#include ` at the top of your devicetree file, and add a `color-mapping` property like: -``` +```dts led_strip: ws2812@0 { compatible = "worldsemi,ws2812-spi"; label = "WS2812"; @@ -108,7 +108,7 @@ Zephyr moved to using a `chosen` node named `zephyr,display` to select the displ For example, for a shield with: -``` +```dts &pro_micro_i2c { status = "okay"; @@ -132,7 +132,7 @@ For example, for a shield with: You would add a `chosen` node like: -``` +```dts / { chosen { zephyr,display = &oled; @@ -148,7 +148,7 @@ two sections of the `.dts` file need updating. Underneath the USB device, add the CDC ACM node: -``` +```dts &usbd { status = "okay"; cdc_acm_uart: cdc_acm_uart { @@ -160,7 +160,7 @@ Underneath the USB device, add the CDC ACM node: Then, an additional `chosen` node (near the top of the file) will mark the CDC ACM device as the console: -``` +```dts / { chosen { ... @@ -175,7 +175,7 @@ Then, an additional `chosen` node (near the top of the file) will mark the CDC A Previously, to get ZMK to build a UF2 image to flash to a given board required adding a `CMakeLists.txt` file that added a custom post build command. Now, the only thing necessary to have Zephyr build a UF2 is to add the following to your `_defconfig` file: -``` +```ini CONFIG_BUILD_OUTPUT_UF2=y ``` @@ -187,7 +187,7 @@ For more details on the implementation, see [zephyr#31066](https://github.com/ze Clock configuration moved to devicetree as well, out of the Kconfig files. Here is a sample config for a board that uses the HSI for the PLL source: -``` +```dts &clk_hsi { status = "okay"; }; diff --git a/docs/blog/2022-04-10-zmk-sotf-5.md b/docs/blog/2022-04-10-zmk-sotf-5.md index b0dd6310..4ea62a31 100644 --- a/docs/blog/2022-04-10-zmk-sotf-5.md +++ b/docs/blog/2022-04-10-zmk-sotf-5.md @@ -32,7 +32,7 @@ to the host capitalized until a non-alpha, non-"continue list" keycode is sent. [petejohanson], taking heavy inspiration on the initial work from [okke-formsma], added [macro support](/docs/behaviors/macros) in [#1168](https://github.com/zmkfirmware/zmk/pull/1166). Several [common patterns](/docs/behaviors/macros#common-patterns) are documented, but one example, changing the underglow color as you activate/deactivate a layer, looks like: -``` +```dts ZMK_MACRO(layer_color_macro, wait-ms = <0>; tap-ms = <0>; @@ -50,7 +50,7 @@ ZMK_MACRO(layer_color_macro, [kurtis-lew] worked diligently to add the [tap-dance behavior](/docs/behaviors/tap-dance) in [#1139](https://github.com/zmkfirmware/zmk/pull/1139), allowing different behaviors to be invoked based on the number of times a user taps a single key in their keymap, e.g. -``` +```dts / { behaviors { td0: tap_dance_0 { @@ -80,7 +80,7 @@ a user taps a single key in their keymap, e.g. Example: -``` +```dts / { conditional_layers { compatible = "zmk,conditional-layers"; @@ -164,7 +164,7 @@ using "high voltage mode" with that SoC. [petejohanson]'s work on the HID foundation also included adding support for full NKRO HID in [#726](https://github.com/zmkfirmware/zmk/pull/726) that can be enabled by adding the following to your `.conf` file for your config: -``` +```ini CONFIG_ZMK_HID_REPORT_TYPE_NKRO=y ``` @@ -176,7 +176,7 @@ It's been live for a while, but [nicell] added an amazing [power profiler](/powe [malinges](https://github.com/malinges) added support for configuring min/max underglow brightness in [#944](https://github.com/zmkfirmware/zmk/pull/944) by setting the values in your `.conf` file as percentages of full: -``` +```ini CONFIG_ZMK_RGB_UNDERGLOW_BRT_MIN=20 CONFIG_ZMK_RGB_UNDERGLOW_BRT_MAX=80 ``` diff --git a/docs/blog/2023-04-06-zephyr-3-2.md b/docs/blog/2023-04-06-zephyr-3-2.md index 693d93dc..69ecb6dd 100644 --- a/docs/blog/2023-04-06-zephyr-3-2.md +++ b/docs/blog/2023-04-06-zephyr-3-2.md @@ -26,7 +26,7 @@ Existing user config repositories using Github Actions to build will pull down Z 1. Replace the contents of your `.github/workflows/build.yml` with: - ``` + ```yaml on: [push, pull_request, workflow_dispatch] jobs: @@ -36,7 +36,7 @@ Existing user config repositories using Github Actions to build will pull down Z 1. If it doesn't exist already, add a new file to your repository named `build.yaml`: - ``` + ```yaml # This file generates the GitHub Actions matrix # For simple board + shield combinations, add them # to the top level board and shield arrays, for more @@ -63,12 +63,12 @@ If you have a custom GitHub Actions workflow you need to maintain for some reaso - Change `zmkfirmware/zmk-build-arm:2.5` to `zmkfirmware/zmk-build-arm:stable` wherever it is found - Locate and delete the lines for the DTS output step, which is no longer needed: - ``` - - name: ${{ steps.variables.outputs.display-name }} DTS File - if: ${{ always() }} - run: | - if [ -f "build/zephyr/${{ matrix.board }}.pre.tmp" ]; then cat -n build/zephyr/${{ matrix.board }}.pre.tmp; fi - if [ -f "build/zephyr/zephyr.dts" ]; then cat -n build/zephyr/zephyr.dts; fi + ```yaml + - name: ${{ steps.variables.outputs.display-name }} DTS File + if: ${{ always() }} + run: | + if [ -f "build/zephyr/${{ matrix.board }}.pre.tmp" ]; then cat -n build/zephyr/${{ matrix.board }}.pre.tmp; fi + if [ -f "build/zephyr/zephyr.dts" ]; then cat -n build/zephyr/zephyr.dts; fi ``` ### VS Code & Docker (Dev Container) @@ -107,7 +107,7 @@ A few testers have reported inconsistent issues with bluetooth connections on Wi Zephyr 3.2 introduced [a new Kconfig setting](https://github.com/zephyrproject-rtos/zephyr/pull/48929) that can be used to work around a bug in Windows related to battery reporting. Check out our [bluetooth config](/docs/config/bluetooth) for the full details. The key new configuration that can be set if using Windows is: -``` +```ini CONFIG_BT_GATT_ENFORCE_SUBSCRIPTION=n ``` @@ -133,7 +133,7 @@ The main area this affects existing shields is those with board specific overrid Previously in ZMK, we relied on per-driver devicetree source properties to set the alternate pin functions for things like SPI or I2C. For example, here is the I2C bus setup as it was previously on the `nice_nano` board: -``` +```dts &i2c0 { compatible = "nordic,nrf-twi"; sda-pin = <17>; @@ -143,7 +143,7 @@ Previously in ZMK, we relied on per-driver devicetree source properties to set t With the move to the `pinctrl` system, this setup now look like: -``` +```dts &i2c0 { compatible = "nordic,nrf-twi"; pinctrl-0 = <&i2c0_default>; @@ -154,7 +154,7 @@ With the move to the `pinctrl` system, this setup now look like: which references the `pinctrl` configuration: -``` +```dts &pinctrl { i2c0_default: i2c0_default { group1 { @@ -185,7 +185,7 @@ The approach is the following when updating a _board_: 1. Add a new file with the naming convention `-pinctrl.dtsi` to your board directory. 1. In the new file, add your `pinctrl` entries that set up different pin control configurations for whatever peripherals/buses are needed. Here's the nice!nano file as an example: - ``` + ```dts /* * Copyright (c) 2022 The ZMK Contributors * SPDX-License-Identifier: MIT @@ -230,7 +230,7 @@ The approach is the following when updating a _board_: 1. From the main `.dts` file, add an `#include "-pinctrl.dtsi"` to have the C-preprocessor combine the files. 1. Update the various peripheral nodes to use the new `pinctrl` configurations. For example, the following old configuration: - ``` + ```dts &i2c0 { compatible = "nordic,nrf-twi"; sda-pin = <15>; @@ -240,7 +240,7 @@ The approach is the following when updating a _board_: would be changed to: - ``` + ```dts &i2c0 { compatible = "nordic,nrf-twi"; pinctrl-0 = <&i2c0_default>; diff --git a/docs/blog/2023-06-18-encoder-refactors.md b/docs/blog/2023-06-18-encoder-refactors.md index 26f9cee8..14be81c8 100644 --- a/docs/blog/2023-06-18-encoder-refactors.md +++ b/docs/blog/2023-06-18-encoder-refactors.md @@ -35,7 +35,7 @@ Splitting these two parts of the encoder configuration allows greater flexibilit Previously, an encoder configuration looked like: -``` +```dts left_encoder: encoder_left { compatible = "alps,ec11"; label = "LEFT_ENCODER"; @@ -47,7 +47,7 @@ Previously, an encoder configuration looked like: Here, the `resolution` property was used to indicate how many encoder pulses should trigger the sensor behavior one time. Next, the encoder is selected in the sensors node: -``` +```dts sensors { compatible = "zmk,keymap-sensors"; sensors = <&left_encoder &right_encoder>; @@ -58,7 +58,7 @@ That was the entirety of the configuration for encoders. ### New Configuration -``` +```dts left_encoder: encoder_left { compatible = "alps,ec11"; label = "LEFT_ENCODER"; @@ -70,7 +70,7 @@ That was the entirety of the configuration for encoders. Here, the `steps` property is now used to indicate how many encoder pulses there are in a single complete rotation of the encoder. Next, the encoder is selected in the sensors node as before, but an additional configuration is used to indicate how many times the encoder should trigger the behavior in your keymap per rotation: -``` +```dts sensors { compatible = "zmk,keymap-sensors"; sensors = <&left_encoder &right_encoder>; @@ -84,7 +84,7 @@ For tactile encoders that have detents, the `triggers-per-rotation` would match The configuration changes bring ZMK's code in line with how upstream Zephyr sensor drivers handle rotations. This has the added advantage of allowing us to leverage other sensor drivers. On Nordic MCUs, like nRF52840, the NRFX QDEC driver can be used, for example: -``` +```dts &pinctrl { qdec_default: qdec_default { group1 { diff --git a/docs/docs/behaviors/backlight.md b/docs/docs/behaviors/backlight.md index 8c613fe6..322530e3 100644 --- a/docs/docs/behaviors/backlight.md +++ b/docs/docs/behaviors/backlight.md @@ -12,7 +12,7 @@ This page contains [backlight](../features/backlight.md) behaviors supported by Backlight actions defines are provided through the [`dt-bindings/zmk/backlight.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/backlight.h) header, which is added at the top of the keymap file: -``` +```dts #include ``` @@ -46,13 +46,13 @@ However the settings will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNC 1. Toggle backlight on/off - ``` + ```dts &bl BL_TOG ``` 1. Sets a specific brightness - ``` + ```dts &bl BL_SET 50 ``` diff --git a/docs/docs/behaviors/bluetooth.md b/docs/docs/behaviors/bluetooth.md index 89496948..1d461722 100644 --- a/docs/docs/behaviors/bluetooth.md +++ b/docs/docs/behaviors/bluetooth.md @@ -20,7 +20,7 @@ A ZMK device may show as "connected" on multiple hosts at the same time. This is Bluetooth command defines are provided through the [`dt-bindings/zmk/bt.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/bt.h) header, which is added at the top of the keymap file: -``` +```dts #include ``` @@ -54,25 +54,25 @@ The bluetooth behavior completes an bluetooth action given on press. 1. Behavior binding to clear the paired host for the selected profile: - ``` + ```dts &bt BT_CLR ``` 1. Behavior binding to select the next profile: - ``` + ```dts &bt BT_NXT ``` 1. Behavior binding to select the previous profile: - ``` + ```dts &bt BT_PRV ``` 1. Behavior binding to select the 2nd profile (passed parameters are [zero based](https://en.wikipedia.org/wiki/Zero-based_numbering)): - ``` + ```dts &bt BT_SEL 1 ``` diff --git a/docs/docs/behaviors/caps-word.md b/docs/docs/behaviors/caps-word.md index e5d862d7..0233de52 100644 --- a/docs/docs/behaviors/caps-word.md +++ b/docs/docs/behaviors/caps-word.md @@ -15,7 +15,7 @@ The modifiers are applied only to to the alphabetic (`A` to `Z`) keycodes, to av Example: -``` +```dts &caps_word ``` @@ -25,7 +25,7 @@ Example: 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: -``` +```dts &caps_word { continue-list = ; }; @@ -41,7 +41,7 @@ By default, the caps word will remain active when any alphanumeric character or In addition, if you would like _multiple_ modifiers, instead of just `MOD_LSFT`, you can override the `mods` property: -``` +```dts &caps_word { mods = <(MOD_LSFT | MOD_LALT)>; }; @@ -57,7 +57,7 @@ In addition, if you would like _multiple_ modifiers, instead of just `MOD_LSFT`, If you want to use multiple caps breaks with different codes to break the caps, you can add additional caps words instances to use in your keymap: -``` +```dts / { prog_caps: behavior_prog_caps_word { compatible = "zmk,behavior-caps-word"; diff --git a/docs/docs/behaviors/hold-tap.md b/docs/docs/behaviors/hold-tap.md index ec66b34f..96e03a0e 100644 --- a/docs/docs/behaviors/hold-tap.md +++ b/docs/docs/behaviors/hold-tap.md @@ -55,7 +55,7 @@ If you press a tapped hold-tap again within `quick-tap-ms` milliseconds of the f For example, the following hold-tap configuration enables `require-prior-idle-ms` with a 125 millisecond term, alongside `quick-tap-ms` with a 200 millisecond term. -``` +```dts rpi: require_prior_idle { compatible = "zmk,behavior-hold-tap"; label = "REQUIRE_PRIOR_IDLE"; @@ -78,7 +78,7 @@ If `retro-tap` is enabled, the tap behavior is triggered when releasing the hold For example, if you press `&mt LEFT_SHIFT A` and then release it without pressing another key, it will output `a`. -``` +```dts &mt { retro-tap; }; @@ -96,7 +96,7 @@ Note that `hold-trigger-key-positions` is an array of key position indexes. Key See the following example, which uses a hold-tap behavior definition, configured with the `hold-preferred` flavor, and with positional hold-tap enabled: -``` +```dts #include #include @@ -141,7 +141,7 @@ The two parameters that are passed to the hold-tap in your keymap will be forwar If you use behaviors that accept no parameters such as [mod-morphs](mod-morph.md) or [macros](macros.md), you can pass a dummy parameter value such as `0` to the hold-tap when you use it in your keymap. For instance, a hold-tap with node label `caps` and `bindings = <&kp>, <&caps_word>;` can be used in the keymap as below to send the caps lock keycode on hold and invoke the [caps word behavior](caps-word.md) on tap: -``` +```dts &caps CAPS 0 ``` @@ -166,7 +166,7 @@ The following are suggested hold-tap configurations that work well with home row ##### Option 1: cross-hand only modifiers, using `tap-unless-interrupted` and positional hold-tap (`hold-trigger-key-positions`) -```dtsi title="Homerow Mods: Cross-hand Example" +```dts title="Homerow Mods: Cross-hand Example" #include #include @@ -198,7 +198,7 @@ The following are suggested hold-tap configurations that work well with home row ##### Option 2: `tap-preferred` -```dtsi title="Homerow Mods: Tap-Preferred Example" +```dts title="Homerow Mods: Tap-Preferred Example" #include #include @@ -228,7 +228,7 @@ The following are suggested hold-tap configurations that work well with home row ##### Option 3: `balanced` -```dtsi title="Homerow Mods: Balanced Example" +```dts title="Homerow Mods: Balanced Example" #include #include @@ -262,7 +262,7 @@ The following are suggested hold-tap configurations that work well with home row A popular method of implementing Autoshift in ZMK involves a C-preprocessor macro, commonly defined as `AS(keycode)`. This macro applies the `LSHIFT` modifier to the specified `keycode` when `AS(keycode)` is held, and simply performs a [keypress](key-press.md), `&kp keycode`, when the `AS(keycode)` binding is tapped. This simplifies the use of Autoshift in a keymap, as the complete hold-tap bindings for each desired Autoshift key, as in `&as LS() &as LS() ... &as LS() `, can be quite cumbersome to use when applied to a large portion of the keymap. -```dtsi title="Hold-Tap Example: Autoshift" +```dts title="Hold-Tap Example: Autoshift" #include #include @@ -298,7 +298,7 @@ A popular method of implementing Autoshift in ZMK involves a C-preprocessor macr This hold-tap example implements a [momentary-layer](layers.md/#momentary-layer) when the keybind is held and a [toggle-layer](layers.md/#toggle-layer) when it is tapped. Similar to the Autoshift and Sticky Hold use-cases, a `MO_TOG(layer)` macro is defined such that the `&mo` and `&tog` behaviors can target a single layer. -```dtsi title="Hold-Tap Example: Momentary layer on Hold, Toggle layer on Tap" +```dts title="Hold-Tap Example: Momentary layer on Hold, Toggle layer on Tap" #include #include diff --git a/docs/docs/behaviors/key-press.md b/docs/docs/behaviors/key-press.md index e8304d77..a298d040 100644 --- a/docs/docs/behaviors/key-press.md +++ b/docs/docs/behaviors/key-press.md @@ -27,7 +27,7 @@ To make it easier to encode the HID keycode numeric values, most keymaps include the [`dt-bindings/zmk/keys.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/keys.h) header provided by ZMK near the top: -``` +```dts #include ``` @@ -44,6 +44,6 @@ The "key press" behavior sends standard keycodes on press/release. Example: -``` +```dts &kp A ``` diff --git a/docs/docs/behaviors/key-repeat.md b/docs/docs/behaviors/key-repeat.md index 5217bce8..9772fdb4 100644 --- a/docs/docs/behaviors/key-repeat.md +++ b/docs/docs/behaviors/key-repeat.md @@ -13,7 +13,7 @@ The key repeat behavior when triggered will send whatever keycode was last sent/ Example: -``` +```dts &key_repeat ``` @@ -25,7 +25,7 @@ By default, the key repeat will only track the last pressed key from the HID "Ke If you'd rather have the repeat also capture and send Consumer page usages, you can update the existing behavior: -``` +```dts &key_repeat { usage-pages = ; }; diff --git a/docs/docs/behaviors/key-toggle.md b/docs/docs/behaviors/key-toggle.md index 85b328f8..080b5b53 100644 --- a/docs/docs/behaviors/key-toggle.md +++ b/docs/docs/behaviors/key-toggle.md @@ -18,7 +18,7 @@ Example uses for key toggle include shift lock, or `ALT-TAB` window switching wi Example: -``` +```dts &kt LALT ``` diff --git a/docs/docs/behaviors/layers.md b/docs/docs/behaviors/layers.md index 7d790156..162b792f 100644 --- a/docs/docs/behaviors/layers.md +++ b/docs/docs/behaviors/layers.md @@ -16,7 +16,7 @@ add a set of `#define`s at the top of your keymap file, and use those layer in y For example, if you have three layers, you can add the following to the top of your keymap: -``` +```dts #define DEFAULT 0 #define LOWER 1 #define RAISE 2 @@ -37,7 +37,7 @@ again. Example: -``` +```dts &mo LOWER ``` @@ -53,7 +53,7 @@ The "layer-tap" behavior enables a layer when a key is held, and outputs a [keyp Example: -``` +```dts < LOWER SPACE ``` @@ -61,7 +61,7 @@ Example: You can configure a different tapping term or tweak other properties noted in the [hold-tap](hold-tap.md#advanced-configuration) documentation page in your keymap: -``` +```dts < { tapping-term-ms = <200>; }; @@ -93,7 +93,7 @@ The "to layer" behavior enables a layer and disables _all_ other layers _except_ Example: -``` +```dts &to 3 ``` @@ -108,13 +108,13 @@ The "toggle layer" behavior enables a layer until the layer is manually disabled Example: -``` +```dts &tog LOWER ``` "Toggle layer" for a : -``` +```dts #define DEFAULT 0 #define NAVI 1 diff --git a/docs/docs/behaviors/macros.md b/docs/docs/behaviors/macros.md index 377ce7fe..7ce968e9 100644 --- a/docs/docs/behaviors/macros.md +++ b/docs/docs/behaviors/macros.md @@ -14,7 +14,7 @@ Each macro you want to use in your keymap gets defined first, then bound in your A macro definition looks like: -``` +```dts / { macros { zed_em_kay: zed_em_kay { @@ -38,7 +38,7 @@ used to reference the macro in your keymap. The macro can then be bound in your keymap by referencing it by the label `&zed_em_kay`, e.g.: -``` +```dts raise_layer { bindings = <&zed_em_kay>; }; @@ -54,7 +54,7 @@ with [modifier functions](../codes/modifiers.mdx#modifier-functions) can be used Like [hold-taps](/docs/behaviors/hold-tap), macros are created by composing other behaviors, and any of those behaviors can be added to the `bindings` list, e.g.: -``` +```dts bindings = <&to 1> , <&bl BL_ON> @@ -86,7 +86,7 @@ To modify the activation mode, macro controls can be added at any point in the ` A concrete example, used to hold a modifier, tap multiple keys, then release the modifier, would look like: -``` +```dts bindings = <¯o_press &kp LSHFT> , <¯o_tap &kp Z &kp M &kp K> @@ -101,7 +101,7 @@ the macro itself is released. To pause the macro until release, use `¯o_pause_for_release`. For example, this macro will press a modifier and activate a layer when the macro is pressed. Once the macro is released, it will release the modifier and deactivate the layer by releasing the `&mo`: -``` +```dts bindings = <¯o_press &mo 1 &kp LSHFT> , <¯o_pause_for_release> @@ -116,7 +116,7 @@ which is equal to the value of [`CONFIG_ZMK_MACRO_DEFAULT_WAIT_MS`](../config/be be set by assigning a value to the `wait-ms` property of the macro, e.g. `wait-ms = <20>;`. If you want to update the wait time at any point in the macro bindings list, use `¯o_wait_time`, e.g. `¯o_wait_time 30`. A full example: -``` +```dts wait-ms = <10>; bindings = <&kp F &kp A &kp S &kp T> @@ -132,7 +132,7 @@ which is equal to the value of [`CONFIG_ZMK_MACRO_DEFAULT_TAP_MS`](../config/beh be set by assigning a value to the `tap-ms` property of the macro, e.g. `tap-ms = <20>;`. If you want to update the tap time at any point in a macro bindings list, use `¯o_tap_time`, e.g. `¯o_tap_time 30`. A full example: -``` +```dts bindings = <¯o_tap_time 10> , <&kp S &kp H &kp O &kp R &kp T> @@ -153,7 +153,7 @@ Another limit worth noting is that the maximum number of bindings you can pass t Macros can also be "parameterized", allowing them to be bound in your keymap with unique values passed into them, e.g.: -``` +```dts raise_layer { bindings = <&my_one_param_macro A> }; @@ -262,7 +262,7 @@ lm: lm { 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: -``` +```dts wait-ms = <0>; tap-ms = <0>; bindings @@ -278,7 +278,7 @@ bindings The other common use case for macros is to sending sequences of keycodes to the connected host. Here, a wait and tap time of at least 30ms is recommended to avoid having HID notifications grouped at the BLE protocol level and then processed out of order: -``` +```dts wait-ms = <40>; tap-ms = <40>; bindings @@ -292,7 +292,7 @@ bindings Many operating systems allow a special sequence to input unicode characters, e.g. [Windows alt codes](https://support.microsoft.com/en-us/office/insert-ascii-or-unicode-latin-based-symbols-and-characters-d13f58d3-7bcb-44a7-a4d5-972ee12e50e0). You can use macros to automate inputting the sequences, e.g. below macro inserts `£` on Windows: -``` +```dts wait-ms = <40>; tap-ms = <40>; bindings @@ -306,7 +306,7 @@ bindings To avoid repetition or possible typos when declaring a **zero parameter macro**, a convenience _C_ macro, named `ZMK_MACRO(name, props)` can be used to simplify things: -``` +```dts ZMK_MACRO(my_zero_param_macro, wait-ms = <30>; tap-ms = <40>; @@ -320,7 +320,7 @@ To avoid repetition or possible typos when declaring a **zero parameter macro**, 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 my_zero_param_macro: my_zero_param_macro { compatible = "zmk,behavior-macro"; label = "ZM_my_macro"; diff --git a/docs/docs/behaviors/misc.md b/docs/docs/behaviors/misc.md index 446ba33c..c71f87c0 100644 --- a/docs/docs/behaviors/misc.md +++ b/docs/docs/behaviors/misc.md @@ -21,7 +21,7 @@ passed down to the next active layer in the stack. Example: -``` +```dts &trans ``` @@ -37,6 +37,6 @@ be passed down to the next active layer in the stack. Example: -``` +```dts &none ``` diff --git a/docs/docs/behaviors/mod-morph.md b/docs/docs/behaviors/mod-morph.md index 33d18e33..6099b428 100644 --- a/docs/docs/behaviors/mod-morph.md +++ b/docs/docs/behaviors/mod-morph.md @@ -18,7 +18,7 @@ The Mod-Morph behavior acts as one of two keycodes, depending on if the required An example of how to implement the mod-morph "Grave Escape": -``` +```dts / { behaviors { gresc: grave_escape { @@ -41,7 +41,7 @@ Note that this specific mod-morph exists in ZMK by default using code `&gresc`. Example: -``` +```dts &gresc ``` @@ -62,7 +62,7 @@ Available Modifiers: Example: -``` +```dts mods = <(MOD_LGUI|MOD_LSFT|MOD_RGUI|MOD_RSFT)>; ``` @@ -74,7 +74,7 @@ When a modifier specified in `mods` is being held, it won't be sent along with t For example, the following configuration morphs `LEFT_SHIFT` + `BACKSPACE` into `DELETE`, and morphs `RIGHT_SHIFT` + `BACKSPACE` into `RIGHT_SHIFT` + `DELETE`. -``` +```dts / { behaviors { bspc_del: backspace_delete { diff --git a/docs/docs/behaviors/mod-tap.md b/docs/docs/behaviors/mod-tap.md index 5f4fa506..d789a8b7 100644 --- a/docs/docs/behaviors/mod-tap.md +++ b/docs/docs/behaviors/mod-tap.md @@ -24,7 +24,7 @@ The Mod-Tap behavior either acts as a held modifier, or as a tapped keycode. Example: -``` +```dts &mt LSHIFT A ``` @@ -32,7 +32,7 @@ Example: You can configure a different tapping term in your keymap: -``` +```dts &mt { tapping-term-ms = <400>; }; diff --git a/docs/docs/behaviors/outputs.md b/docs/docs/behaviors/outputs.md index dad52be2..46b567cf 100644 --- a/docs/docs/behaviors/outputs.md +++ b/docs/docs/behaviors/outputs.md @@ -23,7 +23,7 @@ to select the BLE output through below behavior to be able to send keystrokes to Output command defines are provided through the [`dt-bindings/zmk/outputs.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/outputs.h) header, which is added at the top of the keymap file: -``` +```dts #include ``` @@ -53,18 +53,18 @@ However it will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE`](../con 1. Behavior binding to prefer sending keyboard output to USB - ``` + ```dts &out OUT_USB ``` 1. Behavior binding to prefer sending keyboard output to the current bluetooth profile - ``` + ```dts &out OUT_BLE ``` 1. Behavior binding to toggle between preferring USB and BLE - ``` + ```dts &out OUT_TOG ``` diff --git a/docs/docs/behaviors/power.md b/docs/docs/behaviors/power.md index 11f92084..5251d76c 100644 --- a/docs/docs/behaviors/power.md +++ b/docs/docs/behaviors/power.md @@ -24,7 +24,7 @@ The following boards currently support this feature: External power control command defines are provided through the [`dt-bindings/zmk/ext_power.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/ext_power.h) header, which is added at the top of the keymap file: -``` +```dts #include ``` @@ -52,19 +52,19 @@ However it will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE`](../con 1. Behavior binding to enable the external power - ``` + ```dts &ext_power EP_ON ``` 1. Behavior binding to disable the external power - ``` + ```dts &ext_power EP_OFF ``` 1. Behavior binding to toggle the external power - ``` + ```dts &ext_power EP_TOG ``` diff --git a/docs/docs/behaviors/reset.md b/docs/docs/behaviors/reset.md index 0fc62b2f..b7850eca 100644 --- a/docs/docs/behaviors/reset.md +++ b/docs/docs/behaviors/reset.md @@ -22,7 +22,7 @@ to the device Example: -``` +```dts &sys_reset ``` @@ -38,7 +38,7 @@ you to flash a new firmware. Example: -``` +```dts &bootloader ``` diff --git a/docs/docs/behaviors/sensor-rotate.md b/docs/docs/behaviors/sensor-rotate.md index 02e56924..3ff69dc6 100644 --- a/docs/docs/behaviors/sensor-rotate.md +++ b/docs/docs/behaviors/sensor-rotate.md @@ -19,7 +19,7 @@ The standard sensor rotation behavior allows fully binding behaviors to be invok Here is an example that binds the [RGB Underglow Behavior](/docs/behaviors/underglow.md) to change the RGB brightness: -``` +```dts / { behaviors { rgb_encoder: rgb_encoder { @@ -55,7 +55,7 @@ Here is an example, showing how send key presses on rotation: First, defining the sensor rotation itself, binding the [Key Press Behavior](/docs/behaviors/key-press.md) twice, then binding it in the `sensor-bindings` property of a keymap layer: -``` +```dts / { behaviors { rot_kp: behavior_sensor_rotate_kp { diff --git a/docs/docs/behaviors/sticky-key.md b/docs/docs/behaviors/sticky-key.md index d881e6b0..8b003f55 100644 --- a/docs/docs/behaviors/sticky-key.md +++ b/docs/docs/behaviors/sticky-key.md @@ -14,13 +14,13 @@ A sticky key stays pressed until another key is pressed. It is often used for 's Example: -``` +```dts &sk LSHIFT ``` You can use any keycode that works for `&kp` as parameter to `&sk`: -``` +```dts &sk LG(LS(LA(LCTRL))) ``` @@ -40,7 +40,7 @@ This setting is enabled by default. It ensures that if a sticky key modifier is #### Example -``` +```dts &sk { release-after-ms = <2000>; quick-release; @@ -56,7 +56,7 @@ This setting is enabled by default. It ensures that if a sticky key modifier is This configuration would apply to all sticky keys. This may not be appropriate if using `quick-release` as you'll lose the ability to chain sticky key modifiers. A better approach for this use case would be to create a new behavior: -``` +```dts / { behaviors { skq: sticky_key_quick_release { diff --git a/docs/docs/behaviors/sticky-layer.md b/docs/docs/behaviors/sticky-layer.md index ac341f77..41c2ccf5 100644 --- a/docs/docs/behaviors/sticky-layer.md +++ b/docs/docs/behaviors/sticky-layer.md @@ -16,7 +16,7 @@ By default, sticky layers stay pressed for a second if you don't press any other Example: -``` +```dts &sl 1 ``` @@ -24,7 +24,7 @@ Example: You can configure a different `release-after-ms` in your keymap: -``` +```dts &sl { release-after-ms = <2000>; }; diff --git a/docs/docs/behaviors/tap-dance.md b/docs/docs/behaviors/tap-dance.md index c68b51dc..ac85b3da 100644 --- a/docs/docs/behaviors/tap-dance.md +++ b/docs/docs/behaviors/tap-dance.md @@ -37,7 +37,7 @@ values={[ This example configures a tap-dance named `td0` that outputs the number of times its binding is pressed from 1-3. -```title="Basic Tap-Dance Example: Counter" +```dts title="Basic Tap-Dance Example: Counter" #include #include @@ -78,7 +78,7 @@ Alphanumeric [`key press`](key-press.md) bindings, like those used for `td0`, wi This example configures a mod-tap inside a tap-dance named `td_mt` that outputs `CAPSLOCK` on a single tap, `LSHIFT` on a single press and hold, and `LCTRL` when the tap-dance is pressed twice. -```title="Advanced Tap-Dance Example: Nested Mod-Tap" +```dts title="Advanced Tap-Dance Example: Nested Mod-Tap" #include #include diff --git a/docs/docs/behaviors/underglow.md b/docs/docs/behaviors/underglow.md index 29f34c2a..f94d9008 100644 --- a/docs/docs/behaviors/underglow.md +++ b/docs/docs/behaviors/underglow.md @@ -12,7 +12,7 @@ This page contains [RGB Underglow](../features/underglow.md) behaviors supported RGB actions defines are provided through the [`dt-bindings/zmk/rgb.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/rgb.h) header, which is added at the top of the keymap file: -``` +```dts #include ``` @@ -65,13 +65,13 @@ However the settings will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNC 1. Toggle underglow on/off - ``` + ```dts &rgb_ug RGB_TOG ``` 1. Set a specific HSB color (green) - ``` + ```dts &rgb_ug RGB_COLOR_HSB(128,100,100) ``` diff --git a/docs/docs/config/index.md b/docs/docs/config/index.md index 1ff1bfa0..3d7aeb48 100644 --- a/docs/docs/config/index.md +++ b/docs/docs/config/index.md @@ -71,7 +71,7 @@ Kconfig is used to configure global settings such as the keyboard name and enabl Kconfig files look like this: -``` +```ini CONFIG_ZMK_SLEEP=y CONFIG_EC11=y CONFIG_EC11_TRIGGER_GLOBAL_THREAD=y @@ -114,7 +114,7 @@ Devicetree files use various file extensions. These indicate the purpose of the Devicetree files look like this: -```devicetree +```dts / { chosen { zmk,kscan = &kscan0; @@ -138,7 +138,7 @@ search through the `.dts` file for your board, `.overlay` file for your shield, A Devicetree node looks like this: -```devicetree +```dts kscan0: kscan { compatible = "zmk,kscan-gpio-matrix"; // more properties and/or nodes... @@ -157,7 +157,7 @@ followed by the node's label, an opening curly brace (`{`), one or more new prop For example, to adjust the debouncing of the `zmk,kscan-gpio-matrix` node shown above, you could add this to your keymap: -```devicetree +```dts &kscan0 { debounce-press-ms = <0>; }; @@ -165,7 +165,7 @@ For example, to adjust the debouncing of the `zmk,kscan-gpio-matrix` node shown If the node you want to edit doesn't have a label, you can also write a new tree and it will be merged with the existing tree, overriding any properties. Adding this to your keymap would be equivalent to the previous example. -```devicetree +```dts / { kscan { debounce-press-ms = <0>; @@ -185,7 +185,7 @@ Example: `property;` If a property has already been set to true and you need to override it to false, use the following command to delete the existing property: -```devicetree +```dts /delete-property/ the-property-name; ``` @@ -240,7 +240,7 @@ Each item in the array should be a label for a GPIO node (the names of which dif Example: -```devicetree +```dts some-gpios = <&gpio0 0 GPIO_ACTIVE_HIGH>, <&gpio0 1 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)> @@ -253,7 +253,7 @@ A path to a node, either as a node reference or as a string. Examples: -``` +```dts property = &label; property = "/path/to/some/node"; ``` diff --git a/docs/docs/config/kscan.md b/docs/docs/config/kscan.md index 296cb4a1..67c37652 100644 --- a/docs/docs/config/kscan.md +++ b/docs/docs/config/kscan.md @@ -88,7 +88,7 @@ By default, a switch will drain current through the internal pull up/down resist Assuming the switches connect each GPIO pin to the ground, the [GPIO flags](https://docs.zephyrproject.org/3.2.0/hardware/peripherals/gpio.html#api-reference) for the elements in `input-gpios` should be `(GPIO_ACTIVE_LOW | GPIO_PULL_UP)`: -```devicetree +```dts kscan0: kscan { compatible = "zmk,kscan-gpio-direct"; input-gpios @@ -137,7 +137,7 @@ The `diode-direction` property must be one of: Given the `diode-direction`, the [GPIO flags](https://docs.zephyrproject.org/3.2.0/hardware/peripherals/gpio.html#api-reference) for the elements in `row-` and `col-gpios` should be set appropriately. The output pins (e.g. columns for `col2row`) should have the flag `GPIO_ACTIVE_HIGH`, and input pins (e.g. rows for `col2row`) should have the flags `(GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)`: -```devicetree +```dts kscan0: kscan { compatible = "zmk,kscan-gpio-matrix"; diode-direction = "col2row"; @@ -229,7 +229,7 @@ One possible way to do this is a 3x4 matrix where the direct GPIO keys are shift ...which can be configured with the following Devicetree code: -```devicetree +```dts / { chosen { zmk,kscan = &kscan0; @@ -316,7 +316,7 @@ The `map` array should be defined using the `RC()` macro from [dt-bindings/zmk/m Any keyboard which is not a grid of 1 unit keys will likely have some unused positions in the matrix. A matrix transform can be used to skip the unused positions so users don't have to set them to `&none` in keymaps. -```devicetree +```dts // numpad.overlay / { chosen { @@ -355,7 +355,7 @@ Any keyboard which is not a grid of 1 unit keys will likely have some unused pos }; ``` -```devicetree +```dts // numpad.keymap / { keymap { @@ -377,7 +377,7 @@ Any keyboard which is not a grid of 1 unit keys will likely have some unused pos Consider a keyboard with a [duplex matrix](https://wiki.ai03.com/books/pcb-design/page/matrices-and-duplex-matrix), where the matrix has twice as many rows and half as many columns as the keyboard has keys. A matrix transform can be used to correct for this so that keymaps can match the layout of the keys, not the layout of the matrix. -```devicetree +```dts / { chosen { zmk,kscan = &kscan0; diff --git a/docs/docs/customization.md b/docs/docs/customization.md index 6fb39f85..4f75e743 100644 --- a/docs/docs/customization.md +++ b/docs/docs/customization.md @@ -48,7 +48,7 @@ default keyboard settings. For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder on Windows 10 may look something like this: -``` +```bash west build -b nice_nano -- -DSHIELD=kyria_left -DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config" ``` @@ -63,7 +63,7 @@ More troubleshooting information for split keyboards can be found [here](trouble You can build additional keyboards with GitHub actions by appending them to `build.yml` in your `zmk-config` folder. For instance assume that we have set up a Corne shield with nice!nano during [initial setup](user-setup.md) and we want to add a Lily58 shield with nice!nano v2. The following is an example `build.yaml` file that would accomplish that: -``` +```yaml include: - board: nice_nano shield: corne_left diff --git a/docs/docs/development/build-flash.md b/docs/docs/development/build-flash.md index f57c4b5c..94bbcdf9 100644 --- a/docs/docs/development/build-flash.md +++ b/docs/docs/development/build-flash.md @@ -76,13 +76,13 @@ For split keyboards, you will have to build and flash each side separately the f By default, the `build` command outputs a single .uf2 file named `zmk.uf2` so building left and then right immediately after will overwrite your left firmware. In addition, you will need to pristine build each side to ensure the correct files are used. To avoid having to pristine build every time and separate the left and right build files, we recommend setting up separate build directories for each half. You can do this by using the `-d` parameter and first building left into `build/left`: -``` +```sh west build -d build/left -b nice_nano -- -DSHIELD=kyria_left ``` and then building right into `build/right`: -``` +```sh west build -d build/right -b nice_nano -- -DSHIELD=kyria_right ``` @@ -99,7 +99,7 @@ Instead of building .uf2 files using the default keymap and config files, you ca For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder on Windows 10 may look something like this: -``` +```sh west build -b nice_nano -- -DSHIELD=kyria_left -DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config" ``` @@ -117,7 +117,7 @@ volume automatically -- we need to delete the default volume before binding it t Then you can bind the `zmk-config` volume to the correct path pointing to your local [zmk-config](customization.md) folder: -``` +```sh docker volume create --driver local -o o=bind -o type=none -o \ device="/full/path/to/your/zmk-config/" zmk-config ``` @@ -137,7 +137,7 @@ Alternatively, if your board supports flashing and you're not developing from within a Dockerized environment, enable Device Firmware Upgrade (DFU) mode on your board and run the following command to flash: -``` +```sh west flash ``` diff --git a/docs/docs/development/ide-integration.md b/docs/docs/development/ide-integration.md index bfcd5def..f0403dbb 100644 --- a/docs/docs/development/ide-integration.md +++ b/docs/docs/development/ide-integration.md @@ -71,7 +71,7 @@ If you are developing inside a Docker container, set the IntelliSense mode to `l Open VS Code's integrated terminal and run the following command: -``` +```sh cmake -P zephyr/cmake/verify-toolchain.cmake ``` diff --git a/docs/docs/development/new-behavior.md b/docs/docs/development/new-behavior.md index 0d70aa3b..aab056c1 100644 --- a/docs/docs/development/new-behavior.md +++ b/docs/docs/development/new-behavior.md @@ -357,7 +357,7 @@ For behaviors that do not require central locality, the following options for up For the purpose of this section, we will discuss the structure of `app/dts/behaviors/gresc.dtsi` below. -```dtsi title="app/dts/behaviors/gresc.dtsi" +```dts title="app/dts/behaviors/gresc.dtsi" /* * Copyright (c) 2020 The ZMK Contributors * @@ -383,7 +383,7 @@ The format of a behavior's `.dtsi` file is identical to declaring an instance of After creating the `.dtsi` from above, update `app/dts/behaviors.dtsi` to include your newly predefined behavior instance, making it accessible by the devicetree. -```dtsi title="app/dts/behaviors.dtsi" +```dts title="app/dts/behaviors.dtsi" #include #include #include diff --git a/docs/docs/development/new-shield.md b/docs/docs/development/new-shield.md index 055afcf6..fa30ca38 100644 --- a/docs/docs/development/new-shield.md +++ b/docs/docs/development/new-shield.md @@ -53,7 +53,7 @@ shield to get it picked up for ZMK, `Kconfig.shield` and `Kconfig.defconfig`. The `Kconfig.shield` file defines any additional Kconfig settings that may be relevant when using this keyboard. For most keyboards, there is just one additional configuration value for the shield itself. -``` +```kconfig config SHIELD_MY_BOARD def_bool $(shields_list_contains,my_board) ``` @@ -62,7 +62,7 @@ This will make sure that a new configuration value named `SHIELD_MY_BOARD` is se **For split boards**, you will need to add configurations for the left and right sides. For example, if your split halves are named `my_board_left` and `my_board_right`, it would look like this: -``` +```kconfig config SHIELD_MY_BOARD_LEFT def_bool $(shields_list_contains,my_board_left) @@ -83,7 +83,7 @@ The updated new default values should always be wrapped inside a conditional on The keyboard name must be less than or equal to 16 characters in length, otherwise the bluetooth advertising might fail and you will not be able to find your keyboard from your device. ::: -``` +```kconfig if SHIELD_MY_BOARD config ZMK_KEYBOARD_NAME @@ -97,7 +97,7 @@ You'll also want to set which half is the central side. Most boards set it to th Then on the peripheral half, you'll want to turn USB on so that it shows USB status on displays properly. Finally, you'll want to turn on the split option for both sides. This can all be seen below. -``` +```kconfig if SHIELD_MY_BOARD_LEFT config ZMK_KEYBOARD_NAME @@ -136,7 +136,7 @@ values={[ The `.overlay` is the devicetree description of the keyboard shield that is merged with the primary board devicetree description before the build. For ZMK, this file at a minimum should include the chosen node named `zmk,kscan` that references a KSCAN driver instance. For a simple 3x3 macropad matrix, this might look something like: -``` +```dts / { chosen { zmk,kscan = &kscan0; @@ -174,7 +174,7 @@ Unlike unibody keyboards, split keyboards have a core .dtsi file with shield ove It is preferred to define only the `col-gpios` or `row-gpios` in the common shield .dtsi, depending on the `diode-direction` value. For `col2row` directed boards like the iris, the shared .dtsi file may look like this: -``` +```dts #include / { @@ -228,9 +228,7 @@ Furthermore, the column offset for the [matrix transform](#optional-matrix-trans because the keyboard's switch matrix is read from left to right, top to bottom. This is exemplified with the iris .overlay files. -``` -// iris_left.overlay - +```dts title=iris_left.overlay #include "iris.dtsi" // Notice that the main dtsi files are included in the overlay. &kscan0 { @@ -245,9 +243,7 @@ This is exemplified with the iris .overlay files. }; ``` -``` -// iris_right.overlay - +```dts title=iris_right.overlay #include "iris.dtsi" &default_transform { // The matrix transform for this board is 6 columns over because the left half is 6 columns wide according to the matrix. @@ -281,9 +277,7 @@ For example, a split board called `my_awesome_split_board` would have the follow In most case you'll only need to use the .conf file that affects both halves of a split board. It's used for adding features like deep-sleep or rotary encoders. -``` -// my_awesome_split_board.conf - +```ini title=my_awesome_split_board.conf CONFIG_ZMK_SLEEP=y ``` @@ -306,7 +300,7 @@ the logical key location as perceived by the end user. All _keymap_ mappings act _Without_ a matrix transform, that intentionally map each key position to the row/column pair that position corresponds to, the default equation to determine that is: -``` +```c ($row * NUMBER_OF_COLUMNS) + $column ``` @@ -316,7 +310,7 @@ Whenever that default key position mapping is insufficient, the `.o Here is an example for the [nice60](https://github.com/Nicell/nice60), which uses an efficient 8x8 GPIO matrix, and uses a transform: -``` +```dts #include / { @@ -419,7 +413,7 @@ values={[ In your configuration file you will need to add the following lines so that the encoders can be enabled/disabled: -``` +```ini # Uncomment to enable encoder # CONFIG_EC11=y # CONFIG_EC11_TRIGGER_GLOBAL_THREAD=y @@ -435,7 +429,7 @@ If building locally for split boards, you may need to add these lines to the spe In your device tree file you will need to add the following lines to define the encoder sensor: -``` +```dts left_encoder: encoder_left { compatible = "alps,ec11"; label = "LEFT_ENCODER"; @@ -452,8 +446,8 @@ Add additional encoders as necessary by duplicating the above lines, replacing ` Once you have defined the encoder sensors, you will have to add them to the list of sensors: -``` -sensors { +```dts + sensors { compatible = "zmk,keymap-sensors"; sensors = <&left_encoder &right_encoder>; }; @@ -465,7 +459,7 @@ In this example, a left_encoder and right_encoder are both added. Additional enc Add the following lines to your overlay file(s) to enable the encoder: -``` +```dts &left_encoder { status = "okay"; }; @@ -479,7 +473,7 @@ For split keyboards, make sure to add left hand encoders to the left .overlay fi Add the following line to your keymap file to add default encoder behavior bindings: -``` +```dts sensor-bindings = <&inc_dec_kp C_VOL_UP C_VOL_DN>; ``` @@ -493,7 +487,7 @@ Add additional bindings as necessary to match the default number of encoders on Once you've fully created the new keyboard shield definition, you should be able to test with a build command like: -``` +```sh west build --pristine -b proton_c -- -DSHIELD=my_board ``` @@ -506,7 +500,7 @@ Alternatively, if your board supports flashing and you're not developing from within a Dockerized environment, enable Device Firmware Upgrade (DFU) mode on your board and run the following command to test your build: -``` +```sh west flash ``` diff --git a/docs/docs/development/posix-board.md b/docs/docs/development/posix-board.md index d0ad571a..5a809c02 100644 --- a/docs/docs/development/posix-board.md +++ b/docs/docs/development/posix-board.md @@ -14,7 +14,7 @@ with a compiler that can target 32-bit POSIX. On Debian, you can do this with: -``` +```sh apt install -y gcc-multilib ``` @@ -23,7 +23,7 @@ apt install -y gcc-multilib To do this, you can build ZMK targeting the `native_posix_64` board. -``` +```sh west build --pristine --board native_posix_64 -- -DZMK_CONFIG=tests/none/normal/ ``` diff --git a/docs/docs/development/usb-logging.md b/docs/docs/development/usb-logging.md index 87cd0e7d..e50e7824 100644 --- a/docs/docs/development/usb-logging.md +++ b/docs/docs/development/usb-logging.md @@ -33,7 +33,7 @@ In Github Actions, you can check the ` Kconfig file` step output to ve for you successfully. ::: -``` +```ini # Turn on logging, and set ZMK logging to debug output CONFIG_ZMK_USB_LOGGING=y ``` @@ -53,7 +53,7 @@ values={[ On Linux, this should be a device like `/dev/ttyACM0` and you can connect with `minicom` or `tio` as usual, e.g.: -``` +```sh sudo tio /dev/ttyACM0 ``` @@ -74,7 +74,7 @@ If you already have the Ardunio IDE installed you can also use its built-in Seri On macOS, the device name is something like `/dev/tty.usbmodemXXXXX` where `XXXXX` is some numerical ID. You can connect to the device with [tio](https://tio.github.io/) (can be installed via [Homebrew](https://formulae.brew.sh/formula/tio)): -``` +```sh sudo tio /dev/tty.usbmodem14401 ``` diff --git a/docs/docs/features/backlight.md b/docs/docs/features/backlight.md index 717361a2..c1b5db5d 100644 --- a/docs/docs/features/backlight.md +++ b/docs/docs/features/backlight.md @@ -16,7 +16,7 @@ Unlike [RGB Underglow](underglow.md), backlight can only control single color LE To enable backlight on your board or shield, add the following line to your `.conf` file of your user config directory as such: -``` +```ini CONFIG_ZMK_BACKLIGHT=y ``` @@ -46,7 +46,7 @@ values={[ First, you must enable PWM by adding the following lines to your `Kconfig.defconfig` file: -``` +```kconfig if ZMK_BACKLIGHT config PWM @@ -60,7 +60,7 @@ endif # ZMK_BACKLIGHT Then you have to add the following lines to your `.dts` file: -``` +```dts &pwm0 { status = "okay"; ch0-pin = <45>; @@ -77,7 +77,7 @@ If your board uses a P-channel MOSFET to control backlight instead of a N-channe Then you have to add the following lines inside the root devicetree node on the same file as before: -``` +```dts / { backlight: pwmleds { compatible = "pwm-leds"; @@ -98,7 +98,7 @@ Note that every LED inside of the backlight node will be treated as a backlight Finally you need to add backlight to the `chosen` element of the root devicetree node: -``` +```dts / { chosen { zmk,backlight = &backlight; @@ -113,7 +113,7 @@ You must first add a `boards/` directory within your shield folder. For each boa Inside your `.defconfig` file, add the following lines: -``` +```kconfig if ZMK_BACKLIGHT config PWM @@ -127,7 +127,7 @@ endif # ZMK_BACKLIGHT Then add the following lines to your `.overlay` file: -``` +```dts &pwm0 { status = "okay"; ch0-pin = <45>; @@ -144,7 +144,7 @@ If your shield uses a P-channel MOSFET to control backlight instead of a N-chann Then you have to add the following lines inside the root devicetree node on the same file: -``` +```dts / { backlight: pwmleds { compatible = "pwm-leds"; @@ -165,7 +165,7 @@ Note that every LED inside of the backlight node will be treated as a backlight Finally you need to add backlight to the `chosen` element of the root devicetree node: -``` +```dts / { chosen { zmk,backlight = &backlight; @@ -175,7 +175,7 @@ Finally you need to add backlight to the `chosen` element of the root devicetree Optionally, on Pro Micro compatible shields you can add a LED GPIO node to your devicetree, this could be useful if you want your shield to be compatible with newer or untested boards. To do that you have to enable `CONFIG_LED_GPIO` in your `.conf` file and then add the following lines inside the root devicetree node of your `.dtsi` or `.dts` file: -``` +```dts / { backlight: gpioleds { compatible = "gpio-leds"; @@ -199,7 +199,7 @@ It is possible to control multiple backlight LEDs at the same time. This is usef In order to do that, first you need to enable PWM for each pin: -``` +```dts &pwm0 { status = "okay"; ch0-pin = <45>; /* LED 0 */ @@ -213,7 +213,7 @@ This part may vary based on your MCU as different MCUs may have a different numb Then you can simply add each of your LED to the backlight node: -``` +```dts backlight: pwmleds { compatible = "pwm-leds"; label = "Backlight LEDs"; diff --git a/docs/docs/features/battery.md b/docs/docs/features/battery.md index 42ba6d40..8bf78207 100644 --- a/docs/docs/features/battery.md +++ b/docs/docs/features/battery.md @@ -26,7 +26,7 @@ Zephyr also provides some drivers for fuel gauge ICs such as the TI bq274xx seri Once you have the sensor driver defined, add a `zmk,battery` property to the `chosen` node and set it to reference the sensor node. For example: -``` +```dts / { chosen { zmk,battery = &vbatt; diff --git a/docs/docs/features/beta-testing.md b/docs/docs/features/beta-testing.md index 4328ccbf..4a159362 100644 --- a/docs/docs/features/beta-testing.md +++ b/docs/docs/features/beta-testing.md @@ -44,7 +44,7 @@ values={[ ]}> -``` +```yaml manifest: remotes: - name: zmkfirmware @@ -61,7 +61,7 @@ manifest: -``` +```yaml manifest: remotes: - name: zmkfirmware @@ -80,7 +80,7 @@ manifest: -``` +```yaml manifest: remotes: - name: zmkfirmware diff --git a/docs/docs/features/bluetooth.md b/docs/docs/features/bluetooth.md index b75b8953..e58e1673 100644 --- a/docs/docs/features/bluetooth.md +++ b/docs/docs/features/bluetooth.md @@ -42,7 +42,7 @@ Management of the bluetooth in ZMK is accomplished using the [`&bt` behavior](.. Some users may experience a poor connection between the keyboard and the host. This might be due to poor quality BLE hardware, a metal enclosure on the keyboard or host, or the distance between them. Increasing the transmit power of the keyboard's BLE radio may reduce the severity of this problem. To do this, set the `CONFIG_BT_CTLR_TX_PWR_PLUS_8` configuration value in the `.conf` file of your user config directory as such: -``` +```ini CONFIG_BT_CTLR_TX_PWR_PLUS_8=y ``` @@ -64,7 +64,7 @@ There are a few known issues related to BLE and ZMK: There is a known issue with Windows failing to update the battery information after connecting to a ZMK keyboard. You can work around this Windows bug by overriding a [Bluetooth config variable](../config/bluetooth.md) to force battery notifications even if a host neglects to subscribe to them: -``` +```ini CONFIG_BT_GATT_ENFORCE_SUBSCRIPTION=n ``` diff --git a/docs/docs/features/combos.md b/docs/docs/features/combos.md index bc1353b4..f4664c54 100644 --- a/docs/docs/features/combos.md +++ b/docs/docs/features/combos.md @@ -10,7 +10,7 @@ Combo keys are a way to combine multiple keypresses to output a different key. F Combos configured in your `.keymap` file, but are separate from the `keymap` node found there, since they are processed before the normal keymap. They are specified like this: -``` +```dts / { combos { compatible = "zmk,combos"; diff --git a/docs/docs/features/conditional-layers.md b/docs/docs/features/conditional-layers.md index a685bcab..7ccfdf23 100644 --- a/docs/docs/features/conditional-layers.md +++ b/docs/docs/features/conditional-layers.md @@ -14,7 +14,7 @@ Another way to think of this feature is as a simple combo system for layers, jus Conditional layers are configured via a `conditional_layers` node in your `.keymap` file as follows: -``` +```dts / { conditional_layers { compatible = "zmk,conditional-layers"; diff --git a/docs/docs/features/debouncing.md b/docs/docs/features/debouncing.md index 40170739..cbea7092 100644 --- a/docs/docs/features/debouncing.md +++ b/docs/docs/features/debouncing.md @@ -56,7 +56,7 @@ per-driver option. For example, if your board/shield has a kscan driver labeled `kscan0` in its `.overlay`, `.dts`, or `.dtsi` files, -```devicetree +```dts kscan0: kscan { compatible = "zmk,kscan-gpio-matrix"; ... @@ -65,7 +65,7 @@ kscan0: kscan { then you could add this to your `.keymap`: -```devicetree +```dts &kscan0 { debounce-press-ms = <3>; debounce-release-ms = <3>; diff --git a/docs/docs/features/encoders.md b/docs/docs/features/encoders.md index 0c493330..10575763 100644 --- a/docs/docs/features/encoders.md +++ b/docs/docs/features/encoders.md @@ -21,7 +21,7 @@ Keyboards and macropads with encoder support will typically take the two EC11 pi Rotation is handled separately as a type of sensor. The behavior for this is set in `sensor-bindings`. See [Sensor Rotation](../behaviors/sensor-rotate.md) for customizing this behavior. -``` +```dts sensor-bindings = ; ``` @@ -33,7 +33,7 @@ Additional encoders can be configured by adding more bindings immediately after As an example, a complete `sensor-bindings` for a Kyria with two encoders could look like: -``` +```dts sensor-bindings = <&inc_dec_kp C_VOL_UP C_VOL_DN &inc_dec_kp PG_UP PG_DN>; ``` diff --git a/docs/docs/features/keymaps.md b/docs/docs/features/keymaps.md index 93c2c825..9778ecba 100644 --- a/docs/docs/features/keymaps.md +++ b/docs/docs/features/keymaps.md @@ -61,7 +61,7 @@ alter the behavior when that specific key position is activated/deactivated. For the "key press" (`kp`) behavior at a certain key position, you must specify _which_ keycode should be used for that key position. -``` +```dts &kp A ``` @@ -69,7 +69,7 @@ In this case, the `A` is actually a define for the raw HID keycode, to make keym For example of a binding that uses two parameters, you can see how "mod-tap" (`mt`) is bound: -``` +```dts &mt LSHIFT D ``` @@ -87,7 +87,7 @@ for what would otherwise be cryptic integer keycodes, etc. This also allows brin The top two lines of most keymaps should include: -``` +```dts #include #include ``` @@ -100,7 +100,7 @@ The second include brings in the defines for all the keycodes (e.g. `A`, `N1`, ` All the remaining keymap nodes will be nested inside of the root devicetree node, like so: -```devicetree +```dts / { // Everything else goes here! }; @@ -111,7 +111,7 @@ All the remaining keymap nodes will be nested inside of the root devicetree node Nested under the devicetree root, is the keymap node. The node _name_ itself is not critical, but the node **MUST** have a property `compatible = "zmk,keymap"` in order to be used by ZMK. -``` +```dts keymap { compatible = "zmk,keymap"; diff --git a/docs/docs/features/underglow.md b/docs/docs/features/underglow.md index 2b1400fc..b5c4c703 100644 --- a/docs/docs/features/underglow.md +++ b/docs/docs/features/underglow.md @@ -28,7 +28,7 @@ Here you can see the RGB underglow feature in action using WS2812 LEDs. To enable RGB underglow on your board or shield, simply enable the `CONFIG_ZMK_RGB_UNDERGLOW` and `CONFIG_*_STRIP` configuration values in the `.conf` file for your board or shield. For example: -``` +```ini CONFIG_ZMK_RGB_UNDERGLOW=y # Use the STRIP config specific to the LEDs you're using CONFIG_WS2812_STRIP=y @@ -45,7 +45,7 @@ A common issue when enabling underglow is that some of the installed LEDs do not The number of underglow LEDs is controlled by the `chain-length` property in the `led_strip` node. You can [change the value of this property](../config/index.md#changing-devicetree-properties) in the `.keymap` file by adding a stanza like this one outside of any other node (i.e. above or below the `/` node): -``` +```dts &led_strip { chain-length = <21>; }; @@ -70,7 +70,7 @@ With nRF52 boards, you can just use `&spi3` and define the pins you want to use. Here's an example on a definition that uses P0.06: -``` +```dts #include &pinctrl { @@ -135,7 +135,7 @@ For other boards, you must select an SPI definition that has the `MOSI` pin as y Here's another example for a non-nRF52 board on `spi3`: -``` +```dts #include &spi3 { @@ -161,7 +161,7 @@ Here's another example for a non-nRF52 board on `spi3`: Once you have your `led_strip` properly defined you need to add it to the root devicetree node `chosen` element: -``` +```dts / { chosen { zmk,underglow = &led_strip; @@ -171,7 +171,7 @@ Once you have your `led_strip` properly defined you need to add it to the root d Finally you need to enable the `CONFIG_ZMK_RGB_UNDERGLOW` and `CONFIG_*_STRIP` configuration values in the `.conf` file of your board (or set a default in the `Kconfig.defconfig`): -``` +```ini CONFIG_ZMK_RGB_UNDERGLOW=y # Use the STRIP config specific to the LEDs you're using CONFIG_WS2812_STRIP=y diff --git a/docs/docs/keymap-example-file.md b/docs/docs/keymap-example-file.md index d8d201af..91213f15 100644 --- a/docs/docs/keymap-example-file.md +++ b/docs/docs/keymap-example-file.md @@ -1,4 +1,4 @@ -``` +```dts #include #include diff --git a/docs/docs/keymap-example.md b/docs/docs/keymap-example.md index 47d1c06b..e526d542 100644 --- a/docs/docs/keymap-example.md +++ b/docs/docs/keymap-example.md @@ -1,4 +1,4 @@ -``` +```dts keymap { compatible = "zmk,keymap"; diff --git a/docs/docs/user-setup.md b/docs/docs/user-setup.md index 9d04c347..2532fe8b 100644 --- a/docs/docs/user-setup.md +++ b/docs/docs/user-setup.md @@ -67,21 +67,21 @@ values={[ ]}> -``` +```bash bash -c "$(curl -fsSL https://zmk.dev/setup.sh)" ``` -``` +```bash bash -c "$(wget https://zmk.dev/setup.sh -O -)" '' --wget ``` -``` +```powershell powershell -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://zmk.dev/setup.ps1'))" ```