refactor(docs): Use .mdx for docs with mdx features
Also applies prettier changes in touched files due to precommit
This commit is contained in:
Cem Aksoylar
parent
00962a7255
commit
f014eb45a7
@ -7,13 +7,16 @@ author_image_url: https://avatars.githubusercontent.com/u/7876996
|
||||
tags: [keyboards, firmware, community]
|
||||
---
|
||||
|
||||
import ThemedImage from '@theme/ThemedImage';
|
||||
import ThemedImage from "@theme/ThemedImage";
|
||||
|
||||
<ThemedImage
|
||||
alt="Shows a screenshot of the Keymap Editor application featuring a graphical layout of the Corne Keyboard with a keymap loaded from the nickcoutsos/keymap-editor-demo-crkbd GitHub repository."
|
||||
sources={{
|
||||
light: require('./assets/2023-11-09-keymap-editor/editor-screenshot-light.png').default,
|
||||
dark: require('./assets/2023-11-09-keymap-editor/editor-screenshot-dark.png').default,
|
||||
light:
|
||||
require("./assets/2023-11-09-keymap-editor/editor-screenshot-light.png")
|
||||
.default,
|
||||
dark: require("./assets/2023-11-09-keymap-editor/editor-screenshot-dark.png")
|
||||
.default,
|
||||
}}
|
||||
/>
|
||||
|
||||
@ -5,7 +5,7 @@ sidebar_label: Backlight
|
||||
|
||||
## Summary
|
||||
|
||||
This page contains [backlight](../features/backlight.md) behaviors supported by ZMK.
|
||||
This page contains [backlight](../features/backlight.mdx) behaviors supported by ZMK.
|
||||
|
||||
## Backlight Action Defines
|
||||
|
||||
|
||||
@ -103,5 +103,5 @@ Please note there are five available Bluetooth profiles by default. If you need
|
||||
:::
|
||||
|
||||
:::note
|
||||
If you clear bond of a paired profile, make sure you do the same thing on the peer device as well (typically achieved by _removing_ or _forgetting_ the bluetooth connection). Otherwise the peer will try to connect to your keyboard whenever it discovers it. But while the MAC address of both devices could remain the same, the security key no longer match: the peer device still possess the old key negotiated in the previous pairing procedure, but our keyboard firmware has deleted that key. So the connection will fail. If you [enabled USB logging](../development/usb-logging.md), you might see a lot of failed connection attempts due to the reason of “Security failed”.
|
||||
If you clear bond of a paired profile, make sure you do the same thing on the peer device as well (typically achieved by _removing_ or _forgetting_ the bluetooth connection). Otherwise the peer will try to connect to your keyboard whenever it discovers it. But while the MAC address of both devices could remain the same, the security key no longer match: the peer device still possess the old key negotiated in the previous pairing procedure, but our keyboard firmware has deleted that key. So the connection will fail. If you [enabled USB logging](../development/usb-logging.mdx), you might see a lot of failed connection attempts due to the reason of “Security failed”.
|
||||
:::
|
||||
|
||||
@ -3,8 +3,8 @@ title: Hold-Tap Behavior
|
||||
sidebar_label: Hold-Tap
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
## Summary
|
||||
|
||||
@ -132,7 +132,7 @@ the hold-tap. For homerow mods, this is not always ideal, because it prevents co
|
||||
|
||||
#### Using different behavior types with hold-taps
|
||||
|
||||
You can create instances of hold-taps invoking most [behavior types](../features/keymaps.md#behaviors) for hold or tap actions, by referencing their node labels in the `bindings` value.
|
||||
You can create instances of hold-taps invoking most [behavior types](../features/keymaps.mdx#behaviors) for hold or tap actions, by referencing their node labels in the `bindings` value.
|
||||
The two parameters that are passed to the hold-tap in your keymap will be forwarded to the referred behaviors, first one to the hold behavior and second one to the tap.
|
||||
|
||||
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.
|
||||
@ -59,7 +59,7 @@ Example:
|
||||
|
||||
### Configuration
|
||||
|
||||
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:
|
||||
You can configure a different tapping term or tweak other properties noted in the [hold-tap](hold-tap.mdx#advanced-configuration) documentation page in your keymap:
|
||||
|
||||
```dts
|
||||
< {
|
||||
@ -74,11 +74,11 @@ You can configure a different tapping term or tweak other properties noted in th
|
||||
```
|
||||
|
||||
:::info
|
||||
Functionally, the layer-tap is a [hold-tap](hold-tap.md) of the ["tap-preferred" flavor](hold-tap.md/#flavors) and a [`tapping-term-ms`](hold-tap.md/#tapping-term-ms) of 200 that takes in a [`momentary layer`](#momentary-layer) and a [keypress](key-press.md) as its "hold" and "tap" parameters, respectively.
|
||||
Functionally, the layer-tap is a [hold-tap](hold-tap.mdx) of the ["tap-preferred" flavor](hold-tap.mdx/#flavors) and a [`tapping-term-ms`](hold-tap.mdx/#tapping-term-ms) of 200 that takes in a [`momentary layer`](#momentary-layer) and a [keypress](key-press.md) as its "hold" and "tap" parameters, respectively.
|
||||
|
||||
For users who want to send a different [keycode](../codes/index.mdx) depending on if the same key is held or tapped, see [Mod-Tap](mod-tap.md).
|
||||
|
||||
Similarly, for users looking to create a keybind like the layer-tap that depending on how long the key is held, invokes behaviors like [sticky keys](sticky-key.md) or [key toggles](key-toggle.md), see [Hold-Tap](hold-tap.md).
|
||||
Similarly, for users looking to create a keybind like the layer-tap that depending on how long the key is held, invokes behaviors like [sticky keys](sticky-key.md) or [key toggles](key-toggle.md), see [Hold-Tap](hold-tap.mdx).
|
||||
|
||||
:::
|
||||
|
||||
|
||||
@ -45,10 +45,10 @@ You can configure a different tapping term in your keymap:
|
||||
```
|
||||
|
||||
:::info
|
||||
Under the hood, the mod-tap is simply a [hold-tap](hold-tap.md) of the ["hold-preferred" flavor](hold-tap.md/#flavors) with a [`tapping-term-ms`](hold-tap.md/#tapping-term-ms) of 200 that takes in two [keypresses](key-press.md) as its "hold" and "tap" parameters. This means that the mod-tap can be used to invoke **any** [keycode](../codes/index.mdx), and is not limited to only activating [modifier keys](../codes/modifiers.mdx) when it is held.
|
||||
Under the hood, the mod-tap is simply a [hold-tap](hold-tap.mdx) of the ["hold-preferred" flavor](hold-tap.mdx/#flavors) with a [`tapping-term-ms`](hold-tap.mdx/#tapping-term-ms) of 200 that takes in two [keypresses](key-press.md) as its "hold" and "tap" parameters. This means that the mod-tap can be used to invoke **any** [keycode](../codes/index.mdx), and is not limited to only activating [modifier keys](../codes/modifiers.mdx) when it is held.
|
||||
|
||||
For users who want to momentarily access a specific [layer](../features/keymaps#layers) while a key is held and send a keycode when the same key is tapped, see [Layer-Tap](layers.md/#layer-tap).
|
||||
|
||||
Similarly, for users looking to create a keybind like the mod-tap that invokes behaviors _other_ than [keypresses](key-press.md), like [sticky keys](sticky-key.md) or [key toggles](key-toggle.md), see [Hold-Tap](hold-tap.md).
|
||||
Similarly, for users looking to create a keybind like the mod-tap that invokes behaviors _other_ than [keypresses](key-press.md), like [sticky keys](sticky-key.md) or [key toggles](key-toggle.md), see [Hold-Tap](hold-tap.mdx).
|
||||
|
||||
:::
|
||||
|
||||
@ -3,8 +3,8 @@ title: Tap-Dance Behavior
|
||||
sidebar_label: Tap-Dance
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
## Summary
|
||||
|
||||
@ -20,7 +20,7 @@ Defines the maximum elapsed time after the last tap-dance keybind press before a
|
||||
|
||||
#### `bindings`
|
||||
|
||||
An array of one or more keybinds. This list can include [any ZMK keycode](../codes/) and any listed ZMK behavior, like [hold-taps](hold-tap.md), or [sticky keys](sticky-key.md). The index of a keybind in the `bindings` array corresponds to the number of times the tap-dance binding is pressed. For example, in the [basic tap-dance counter](#basic-example-counter) shown below, `&kp N2` is the second binding in the array of `bindings`: we then see an output of `2` when the `td0` binding is pressed twice.
|
||||
An array of one or more keybinds. This list can include [any ZMK keycode](../codes/) and any listed ZMK behavior, like [hold-taps](hold-tap.mdx), or [sticky keys](sticky-key.md). The index of a keybind in the `bindings` array corresponds to the number of times the tap-dance binding is pressed. For example, in the [basic tap-dance counter](#basic-example-counter) shown below, `&kp N2` is the second binding in the array of `bindings`: we then see an output of `2` when the `td0` binding is pressed twice.
|
||||
|
||||
The number of bindings in this array also determines the tap-dance's maximum number of keypresses. When a tap-dance reaches its maximum number of keypresses, it will immediately invoke the last behavior in its list of `bindings`, rather than waiting for [`tapping-term-ms`](#tapping-term-ms) to expire before the output is displayed.
|
||||
|
||||
@ -3,7 +3,7 @@ title: Backlight Configuration
|
||||
sidebar_label: Backlight
|
||||
---
|
||||
|
||||
See the [backlight feature page](../features/backlight.md) for more details, including instructions for adding backlight support to a board.
|
||||
See the [backlight feature page](../features/backlight.mdx) for more details, including instructions for adding backlight support to a board.
|
||||
|
||||
See [Configuration Overview](index.md) for instructions on how to change these settings.
|
||||
|
||||
@ -37,4 +37,4 @@ See the Zephyr devicetree bindings for LED drivers:
|
||||
- [gpio-leds](https://docs.zephyrproject.org/3.0.0/reference/devicetree/bindings/gpio/gpio-leds.html)
|
||||
- [pwm-leds](https://docs.zephyrproject.org/latest/build/dts/api/bindings/led/pwm-leds.html)
|
||||
|
||||
See the [backlight feature page](../features/backlight.md) for examples of the properties that must be set to enable backlighting.
|
||||
See the [backlight feature page](../features/backlight.mdx) for examples of the properties that must be set to enable backlighting.
|
||||
|
||||
@ -49,7 +49,7 @@ You can use the following nodes to tweak the default behaviors:
|
||||
|
||||
Creates a custom behavior that triggers one behavior when a key is held or a different one when the key is tapped.
|
||||
|
||||
See the [hold-tap behavior](../behaviors/hold-tap.md) documentation for more details and examples.
|
||||
See the [hold-tap behavior](../behaviors/hold-tap.mdx) documentation for more details and examples.
|
||||
|
||||
### Devicetree
|
||||
|
||||
@ -77,7 +77,7 @@ The `flavor` property may be one of:
|
||||
- `"tap-preferred"`
|
||||
- `"tap-unless-interrupted"`
|
||||
|
||||
See the [hold-tap behavior documentation](../behaviors/hold-tap.md) for an explanation of each flavor.
|
||||
See the [hold-tap behavior documentation](../behaviors/hold-tap.mdx) for an explanation of each flavor.
|
||||
|
||||
`hold-trigger-key-positions` is an array of zero-based key position indices.
|
||||
|
||||
@ -243,7 +243,7 @@ You can use the following nodes to tweak the default behaviors:
|
||||
|
||||
Creates a custom behavior that triggers a different behavior corresponding to the number of times the key is tapped.
|
||||
|
||||
See the [tap dance behavior](../behaviors/tap-dance.md) documentation for more details and examples.
|
||||
See the [tap dance behavior](../behaviors/tap-dance.mdx) documentation for more details and examples.
|
||||
|
||||
### Devicetree
|
||||
|
||||
|
||||
@ -33,7 +33,7 @@ Each child node can have the following properties:
|
||||
|
||||
| Property | Type | Description | Default |
|
||||
| ----------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
|
||||
| `bindings` | phandle-array | A [behavior](../features/keymaps.md#behaviors) to run when the combo is triggered | |
|
||||
| `bindings` | phandle-array | A [behavior](../features/keymaps.mdx#behaviors) to run when the combo is triggered | |
|
||||
| `key-positions` | array | A list of key position indices for the keys which should trigger the combo | |
|
||||
| `timeout-ms` | int | All the keys in `key-positions` must be pressed within this time in milliseconds to trigger the combo | 50 |
|
||||
| `require-prior-idle-ms` | int | If any non-modifier key is pressed within `require-prior-idle-ms` before a key in the combo, the key will not be considered for the combo | -1 (disabled) |
|
||||
|
||||
@ -63,7 +63,7 @@ ZMK will search the shield folder for the following config files:
|
||||
|
||||
Shared config files (excluding any `_left` or `_right` suffix) are not currently supported in shield folders.
|
||||
|
||||
For more documentation on creating and configuring a new shield, see [Zephyr's shield documentation](https://docs.zephyrproject.org/latest/hardware/porting/shields.html) and [ZMK's new keyboard shield](../development/new-shield.md) guide.
|
||||
For more documentation on creating and configuring a new shield, see [Zephyr's shield documentation](https://docs.zephyrproject.org/latest/hardware/porting/shields.html) and [ZMK's new keyboard shield](../development/new-shield.mdx) guide.
|
||||
|
||||
## Kconfig Files
|
||||
|
||||
|
||||
@ -18,9 +18,9 @@ The `zmk,keymap` node itself has no properties. It should have one child node pe
|
||||
Each child node can have the following properties:
|
||||
|
||||
| Property | Type | Description |
|
||||
| ----------------- | ------------- | ---------------------------------------------------------------------- |
|
||||
| ----------------- | ------------- | ----------------------------------------------------------------------- |
|
||||
| `display-name` | string | Name for the layer on displays |
|
||||
| `bindings` | phandle-array | List of [key behaviors](../features/keymaps.md#behaviors), one per key |
|
||||
| `bindings` | phandle-array | List of [key behaviors](../features/keymaps.mdx#behaviors), one per key |
|
||||
| `sensor-bindings` | phandle-array | List of sensor behaviors, one per sensor |
|
||||
|
||||
Items for `bindings` must be listed in the order the keys are defined in the [keyboard scan configuration](kscan.md).
|
||||
|
||||
@ -320,7 +320,7 @@ Transforms should be used any time the physical layout of a keyboard's keys does
|
||||
|
||||
Transforms can also be used for keyboards with multiple layouts. You can define multiple matrix transform nodes, one for each layout, and users can select which one they want from the `/chosen` node in their keymaps.
|
||||
|
||||
See the [new shield guide](../development/new-shield.md#optional-matrix-transform) for more documentation on how to define a matrix transform.
|
||||
See the [new shield guide](../development/new-shield.mdx#optional-matrix-transform) for more documentation on how to define a matrix transform.
|
||||
|
||||
### Devicetree
|
||||
|
||||
|
||||
@ -4,7 +4,7 @@ sidebar_label: Customizing ZMK
|
||||
---
|
||||
|
||||
After verifying you can successfully flash the default firmware, you will probably want to begin customizing your keymap and other keyboard options.
|
||||
[In the initial setup tutorial](user-setup.md), you created a Github repository called `zmk-config`. This repository is a discrete filesystem which works
|
||||
[In the initial setup tutorial](user-setup.mdx), you created a Github repository called `zmk-config`. This repository is a discrete filesystem which works
|
||||
with the main `zmk` firmware repository to build your desired firmware. The main advantage of a discrete configuration folder is ensuring that the
|
||||
working components of ZMK are kept separate from your personal keyboard settings, reducing the amount of file manipulation in the configuration process.
|
||||
This makes flashing ZMK to your keyboard much easier, especially because you don't need to keep an up-to-date copy of zmk on your computer at all times.
|
||||
@ -28,7 +28,7 @@ Refer to the [Configuration](/docs/config) documentation for more details on thi
|
||||
## Keymap
|
||||
|
||||
Once you have the basic user config completed, you can find the keymap file in `config/<keyboard>.keymap` and customize from there.
|
||||
Refer to the [Keymap](features/keymaps.md) documentation to learn more.
|
||||
Refer to the [Keymap](features/keymaps.mdx) documentation to learn more.
|
||||
|
||||
## Publishing
|
||||
|
||||
@ -40,9 +40,9 @@ If you need to, a review of [Learn The Basics Of Git In Under 10 Minutes](https:
|
||||
:::
|
||||
|
||||
:::note
|
||||
It is also possible to build firmware locally on your computer by following the [toolchain setup](development/setup.md) and
|
||||
[building instructions](development/build-flash.md), which includes pointers to
|
||||
[building using your `zmk-config` folder](development/build-flash.md#building-from-zmk-config-folder).
|
||||
It is also possible to build firmware locally on your computer by following the [toolchain setup](development/setup.mdx) and
|
||||
[building instructions](development/build-flash.mdx), which includes pointers to
|
||||
[building using your `zmk-config` folder](development/build-flash.mdx#building-from-zmk-config-folder).
|
||||
:::
|
||||
|
||||
## Flashing Your Changes
|
||||
@ -54,7 +54,7 @@ More troubleshooting information for split keyboards can be found [here](trouble
|
||||
|
||||
## Building Additional Keyboards
|
||||
|
||||
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:
|
||||
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.mdx) 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:
|
||||
|
||||
@ -3,20 +3,24 @@ title: Building and Flashing
|
||||
sidebar_label: Building and Flashing
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
export const OsTabs = (props) => (<Tabs
|
||||
export const OsTabs = (props) => (
|
||||
<Tabs
|
||||
groupId="operating-systems"
|
||||
defaultValue="debian"
|
||||
values={[
|
||||
{label: 'Debian/Ubuntu', value: 'debian'},
|
||||
{label: 'Raspberry OS', value: 'raspberryos'},
|
||||
{label: 'Fedora', value: 'fedora'},
|
||||
{label: 'Windows', value: 'win'},
|
||||
{label: 'macOS', value: 'mac'},
|
||||
]
|
||||
}>{props.children}</Tabs>);
|
||||
{ label: "Debian/Ubuntu", value: "debian" },
|
||||
{ label: "Raspberry OS", value: "raspberryos" },
|
||||
{ label: "Fedora", value: "fedora" },
|
||||
{ label: "Windows", value: "win" },
|
||||
{ label: "macOS", value: "mac" },
|
||||
]}
|
||||
>
|
||||
{props.children}
|
||||
</Tabs>
|
||||
);
|
||||
|
||||
## Building
|
||||
|
||||
@ -110,7 +114,7 @@ west build -b nice_nano_v2 -- -DSHIELD=vendor_shield -DZMK_EXTRA_MODULES="C:/Use
|
||||
|
||||
### Building from `zmk-config` Folder
|
||||
|
||||
Instead of building .uf2 files using the default keymap and config files, you can build directly from your [`zmk-config` folder](../user-setup.md#github-repo) by adding
|
||||
Instead of building .uf2 files using the default keymap and config files, you can build directly from your [`zmk-config` folder](../user-setup.mdx#github-repo) by adding
|
||||
`-DZMK_CONFIG="C:/the/absolute/path/config"` to your `west build` command. **Notice that this path should point to the folder labelled `config` within your `zmk-config` folder.**
|
||||
|
||||
For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder on Windows 10 may look something like this:
|
||||
@ -3,21 +3,25 @@ title: IDE Integration
|
||||
sidebar_label: IDE Integration
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
export const OsTabs = (props) => (<Tabs
|
||||
export const OsTabs = (props) => (
|
||||
<Tabs
|
||||
groupId="operating-systems"
|
||||
defaultValue="debian"
|
||||
values={[
|
||||
{label: 'Debian/Ubuntu', value: 'debian'},
|
||||
{label: 'Windows', value: 'win'},
|
||||
{label: 'macOS', value: 'mac'},
|
||||
{label: 'Raspberry OS', value: 'raspberryos'},
|
||||
{label: 'Fedora', value: 'fedora'},
|
||||
{label: 'VS Code & Docker', value: 'docker'},
|
||||
]
|
||||
}>{props.children}</Tabs>);
|
||||
{ label: "Debian/Ubuntu", value: "debian" },
|
||||
{ label: "Windows", value: "win" },
|
||||
{ label: "macOS", value: "mac" },
|
||||
{ label: "Raspberry OS", value: "raspberryos" },
|
||||
{ label: "Fedora", value: "fedora" },
|
||||
{ label: "VS Code & Docker", value: "docker" },
|
||||
]}
|
||||
>
|
||||
{props.children}
|
||||
</Tabs>
|
||||
);
|
||||
|
||||
## Visual Studio Code
|
||||
|
||||
@ -35,7 +39,7 @@ terminal to the ZMK repository and run the following command:
|
||||
west config build.cmake-args -- -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
|
||||
```
|
||||
|
||||
Every [build](build-flash.md#building) will now update the database. You will
|
||||
Every [build](build-flash.mdx#building) will now update the database. You will
|
||||
need to build once to create the database before code completion will work.
|
||||
We'll tell Visual Studio Code where to find the database in the next step.
|
||||
|
||||
@ -3,14 +3,14 @@ title: New Behavior
|
||||
sidebar_label: New Behavior
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
## Overview
|
||||
|
||||
This document outlines how to develop a behavior for ZMK and prepare the changes for a pull request.
|
||||
|
||||
Behaviors are assigned to key positions and determine what happens when they are pressed and released. They are implemented in Zephyr as "devices": they consist of a devicetree binding file, which specifies the properties of the behavior, and a driver written in C code. This allows for the ability to create unique instances of these behaviors in [keymaps](../features/keymaps.md) or devicetree-source-include files (`.dtsi`). While instances of behaviors stored in keymaps are created by end-users for their personal needs, the instances that live in the .dtsi files are stored and documented in ZMK directly, which removes the need for end-users to set up common use-cases of these behaviors in their personal keymaps.
|
||||
Behaviors are assigned to key positions and determine what happens when they are pressed and released. They are implemented in Zephyr as "devices": they consist of a devicetree binding file, which specifies the properties of the behavior, and a driver written in C code. This allows for the ability to create unique instances of these behaviors in [keymaps](../features/keymaps.mdx) or devicetree-source-include files (`.dtsi`). While instances of behaviors stored in keymaps are created by end-users for their personal needs, the instances that live in the .dtsi files are stored and documented in ZMK directly, which removes the need for end-users to set up common use-cases of these behaviors in their personal keymaps.
|
||||
|
||||
The general process for developing behaviors is:
|
||||
|
||||
@ -192,7 +192,7 @@ The dependencies required for any ZMK behavior are:
|
||||
|
||||
- `device.h`: [Zephyr Device APIs](https://docs.zephyrproject.org/apidoc/latest/group__device__model.html)
|
||||
- `drivers/behavior.h`: ZMK Behavior Functions (e.g. [`locality`](#api-structure), `behavior_keymap_binding_pressed`, `behavior_keymap_binding_released`, `behavior_sensor_keymap_binding_triggered`)
|
||||
- `logging/log.h`: [Zephyr Logging APIs](https://docs.zephyrproject.org/latest/services/logging/index.html) (for more information on USB Logging in ZMK, see [USB Logging](usb-logging.md)).
|
||||
- `logging/log.h`: [Zephyr Logging APIs](https://docs.zephyrproject.org/latest/services/logging/index.html) (for more information on USB Logging in ZMK, see [USB Logging](usb-logging.mdx)).
|
||||
- `zmk/behavior.h`: ZMK Behavior Information (e.g. parameters, position and timestamp of events)
|
||||
- `return` values:
|
||||
- `ZMK_BEHAVIOR_OPAQUE`: Used to terminate `on_<behavior_name>_binding_pressed` and `on_<behavior_name>_binding_released` functions that accept `(struct zmk_behavior_binding *binding, struct zmk_behavior_binding_event event)` as parameters
|
||||
@ -433,7 +433,7 @@ Zephyr currently does not support logging over Bluetooth, so any use of the seri
|
||||
:::info
|
||||
|
||||
- See [Tests](tests.md) for more information on how to create virtual test sets.
|
||||
- For hardware-based testing, see [USB Logging](usb-logging.md).
|
||||
- For hardware-based testing, see [USB Logging](usb-logging.mdx).
|
||||
|
||||
:::
|
||||
|
||||
@ -444,7 +444,7 @@ Consider the following prompts when writing documentation for new behaviors:
|
||||
- What does it do? Describe some general use-cases for the behavior.
|
||||
- Which properties included in the [devicetree binding](#creating-the-devicetree-binding-yaml) should be configured manually by the user? What do they do, and if applicable, what are their default values?
|
||||
- What does an example implementation in a keymap look like? Include a code-snippet of the example implementation in the keymap file's `behaviors` node.
|
||||
- Are there any [common use-cases of the behavior](#defining-common-use-cases-for-the-behavior-dtsi-optional)? Consider making a separate documentation page for these predefined variations, like how the [mod-tap](../behaviors/mod-tap.md) has a separate page from the [hold-tap](../behaviors/hold-tap.md).
|
||||
- Are there any [common use-cases of the behavior](#defining-common-use-cases-for-the-behavior-dtsi-optional)? Consider making a separate documentation page for these predefined variations, like how the [mod-tap](../behaviors/mod-tap.md) has a separate page from the [hold-tap](../behaviors/hold-tap.mdx).
|
||||
- How does the behavior perform in edge cases? For example, tap-dances invoke the last binding in its list of `bindings` once the maximum number of keypresses has been reached.
|
||||
|
||||
Consider also including visual aids alongside written documentation if it adds clarity.
|
||||
@ -2,9 +2,9 @@
|
||||
title: New Keyboard Shield
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
import KeymapExampleFile from '../keymap-example-file.md';
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
import KeymapExampleFile from "../keymap-example-file.md";
|
||||
|
||||
import InterconnectTabs from "@site/src/components/interconnect-tabs";
|
||||
import Metadata from "@site/src/data/hardware-metadata.json";
|
||||
@ -79,7 +79,7 @@ config SHIELD_MY_BOARD
|
||||
def_bool $(shields_list_contains,my_board)
|
||||
```
|
||||
|
||||
This will make sure that a new configuration value named `SHIELD_MY_BOARD` is set to true whenever `my_board` is used as the shield name, either as the `SHIELD` variable [in a local build](build-flash.md) or in your `build.yaml` file [when using Github Actions](../customization). Note that this configuration value will be used in `Kconfig.defconfig` to set other properties about your shield, so make sure that they match.
|
||||
This will make sure that a new configuration value named `SHIELD_MY_BOARD` is set to true whenever `my_board` is used as the shield name, either as the `SHIELD` variable [in a local build](build-flash.mdx) or in your `build.yaml` file [when using Github Actions](../customization). Note that this configuration value will be used in `Kconfig.defconfig` to set other properties about your shield, so make sure that they match.
|
||||
|
||||
**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:
|
||||
|
||||
@ -530,7 +530,7 @@ Add the following line to your keymap file to add default encoder behavior bindi
|
||||
sensor-bindings = <&inc_dec_kp C_VOL_UP C_VOL_DN>;
|
||||
```
|
||||
|
||||
Add additional bindings as necessary to match the default number of encoders on your board. See the [Encoders](../features/encoders.md) and [Keymap](../features/keymaps.md) feature documentation for more details.
|
||||
Add additional bindings as necessary to match the default number of encoders on your board. See the [Encoders](../features/encoders.md) and [Keymap](../features/keymaps.mdx) feature documentation for more details.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
@ -539,7 +539,7 @@ Add additional bindings as necessary to match the default number of encoders on
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
Using GitHub Actions to build your new firmware can save you from doing any local [development setup](./setup.md),
|
||||
Using GitHub Actions to build your new firmware can save you from doing any local [development setup](./setup.mdx),
|
||||
at the expense of a longer feedback loop if there are issues. To push your changes and trigger a build:
|
||||
|
||||
- Add all your pending changes with `git add .`
|
||||
@ -551,7 +551,7 @@ Once pushed, click on the "Actions" tab of the repo you created in the first ste
|
||||
### Local Build
|
||||
|
||||
:::note
|
||||
To build locally, be sure you've followed the [development setup](./setup.md) guide first.
|
||||
To build locally, be sure you've followed the [development setup](./setup.mdx) guide first.
|
||||
:::
|
||||
|
||||
Once you've fully created the new keyboard shield definition,
|
||||
@ -562,7 +562,7 @@ west build --pristine -b nice_nano_v2 -- -DSHIELD=<my_shield> -DZMK_EXTRA_MODULE
|
||||
# replace <my_shield> with e.g. <my_shield>_left for split keyboards, then repeat for <my_shield>_right
|
||||
```
|
||||
|
||||
The above build command generates a `build/zephyr/zmk.uf2` file that you can flash using the steps from the following section. See the dedicated [building and flashing page](build-flash.md) for more details.
|
||||
The above build command generates a `build/zephyr/zmk.uf2` file that you can flash using the steps from the following section. See the dedicated [building and flashing page](build-flash.mdx) for more details.
|
||||
|
||||
### Flashing
|
||||
|
||||
@ -581,9 +581,9 @@ west flash
|
||||
```
|
||||
|
||||
Please have a look at documentation specific to
|
||||
[building and flashing](build-flash.md) for additional information.
|
||||
[building and flashing](build-flash.mdx) for additional information.
|
||||
|
||||
:::note
|
||||
Further testing your keyboard shield without altering the root keymap file can be done with the use of `-DZMK_CONFIG` in your `west build` command,
|
||||
shown [here](build-flash.md#building-from-zmk-config-folder)
|
||||
shown [here](build-flash.mdx#building-from-zmk-config-folder)
|
||||
:::
|
||||
@ -3,21 +3,25 @@ title: Toolchain Setup
|
||||
sidebar_label: Toolchain Setup
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
export const OsTabs = (props) => (<Tabs
|
||||
export const OsTabs = (props) => (
|
||||
<Tabs
|
||||
groupId="operating-systems"
|
||||
defaultValue="debian"
|
||||
values={[
|
||||
{label: 'VS Code & Docker', value: 'docker'},
|
||||
{label: 'Debian/Ubuntu', value: 'debian'},
|
||||
{label: 'Windows', value: 'win'},
|
||||
{label: 'macOS', value: 'mac'},
|
||||
{label: 'Raspberry OS', value: 'raspberryos'},
|
||||
{label: 'Fedora', value: 'fedora'},
|
||||
]
|
||||
}>{props.children}</Tabs>);
|
||||
{ label: "VS Code & Docker", value: "docker" },
|
||||
{ label: "Debian/Ubuntu", value: "debian" },
|
||||
{ label: "Windows", value: "win" },
|
||||
{ label: "macOS", value: "mac" },
|
||||
{ label: "Raspberry OS", value: "raspberryos" },
|
||||
{ label: "Fedora", value: "fedora" },
|
||||
]}
|
||||
>
|
||||
{props.children}
|
||||
</Tabs>
|
||||
);
|
||||
|
||||
This guide will show you how to set up a development environment for building ZMK locally.
|
||||
|
||||
@ -270,7 +274,7 @@ This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can tak
|
||||
:::info
|
||||
If you're using Docker, you're done with setup! You must restart the container at this point. The easiest way to do so is to close the VS Code window, verify that the container has stopped in Docker Dashboard, and reopen the container with VS Code.
|
||||
|
||||
Once your container is restarted, proceed to [Building and Flashing](development/build-flash.md).
|
||||
Once your container is restarted, proceed to [Building and Flashing](development/build-flash.mdx).
|
||||
:::
|
||||
|
||||
### Export Zephyr CMake package
|
||||
@ -2,8 +2,8 @@
|
||||
title: USB Logging
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
## Overview
|
||||
|
||||
@ -21,7 +21,7 @@ It is recommended to only enable logging when needed, and not leaving it on by d
|
||||
## Kconfig
|
||||
|
||||
The `CONFIG_ZMK_USB_LOGGING` Kconfig enables USB logging. This can be set at the keyboard level, typically in the `config/<your_keyboard>.conf`
|
||||
file if you are using a [user config repository](user-setup.md). It can also be enabled at the ZMK level using the `app/prj.conf` file, or other
|
||||
file if you are using a [user config repository](user-setup.mdx). It can also be enabled at the ZMK level using the `app/prj.conf` file, or other
|
||||
search locations described in the [configuration overview](config/index.md#config-file-locations).
|
||||
|
||||
Logging can be further configured using Kconfig described in [the Zephyr documentation](https://docs.zephyrproject.org/3.2.0/services/logging/index.html).
|
||||
@ -79,6 +79,7 @@ sudo tio /dev/tty.usbmodem14401
|
||||
```
|
||||
|
||||
You should see tio printing `Disconnected` or `Connected` when you disconnect or reconnect the USB cable.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
@ -3,8 +3,8 @@ title: Backlight
|
||||
sidebar_label: Backlight
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
Backlight is a feature used to control an array of LEDs, usually placed through or under switches.
|
||||
|
||||
@ -3,8 +3,8 @@ title: Beta Testing
|
||||
sidebar_label: Beta Testing
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
You may find that ZMK does not support a feature or keyboard that you are interesting in using. You may find that someone
|
||||
has already taken the time to submit the feature you need as a [Pull Request](https://github.com/zmkfirmware/zmk/pulls). If you find the feature you need as a pull request,
|
||||
@ -30,7 +30,7 @@ Combos configured in your `.keymap` file, but are separate from the `keymap` nod
|
||||
- `layers = <0 1...>` will allow limiting a combo to specific layers. This is an _optional_ parameter, when omitted it defaults to global scope.
|
||||
- `bindings` is the behavior that is activated when the behavior is pressed.
|
||||
- (advanced) you can specify `slow-release` if you want the combo binding to be released when all key-positions are released. The default is to release the combo as soon as any of the keys in the combo is released.
|
||||
- (advanced) you can specify a `require-prior-idle-ms` value much like for [hold-taps](behaviors/hold-tap.md#require-prior-idle-ms). If any non-modifier key is pressed within `require-prior-idle-ms` before a key in the combo, the combo will not trigger.
|
||||
- (advanced) you can specify a `require-prior-idle-ms` value much like for [hold-taps](behaviors/hold-tap.mdx#require-prior-idle-ms). If any non-modifier key is pressed within `require-prior-idle-ms` before a key in the combo, the combo will not trigger.
|
||||
|
||||
:::info
|
||||
|
||||
|
||||
@ -41,4 +41,4 @@ Here, the left encoder is configured to control volume up and down while the rig
|
||||
|
||||
## Adding Encoder Support
|
||||
|
||||
See the [New Keyboard Shield](../development/new-shield.md#encoders) documentation for how to add or modify additional encoders to your shield.
|
||||
See the [New Keyboard Shield](../development/new-shield.mdx#encoders) documentation for how to add or modify additional encoders to your shield.
|
||||
|
||||
@ -3,8 +3,8 @@ title: Keymaps & Behaviors
|
||||
sidebar_label: Keymaps
|
||||
---
|
||||
|
||||
import KeymapExample from '../keymap-example.md';
|
||||
import KeymapExampleFile from '../keymap-example-file.md';
|
||||
import KeymapExample from "../keymap-example.md";
|
||||
import KeymapExampleFile from "../keymap-example-file.md";
|
||||
|
||||
ZMK uses a declarative approach to keymaps instead of using C code for all keymap configuration.
|
||||
Right now, ZMK uses the devicetree syntax to declare those keymaps; future work is envisioned for
|
||||
@ -6,7 +6,7 @@ sidebar_label: RGB Underglow
|
||||
RGB underglow is a feature used to control "strips" of RGB LEDs. Most of the time this is called underglow and creates a glow underneath the board using a ring of LEDs around the edge, hence the name. However, this can be extended to be used to control anything from a single LED to a long string of LEDs anywhere on the keyboard.
|
||||
|
||||
:::info
|
||||
RGB underglow can also be used for under-key lighting. If you have RGB LEDs on your keyboard, this is what you want. For PWM/single color LEDs, see [Backlight](backlight.md).
|
||||
RGB underglow can also be used for under-key lighting. If you have RGB LEDs on your keyboard, this is what you want. For PWM/single color LEDs, see [Backlight](backlight.mdx).
|
||||
:::
|
||||
|
||||
ZMK supports all the RGB LEDs supported by Zephyr. Here's the current list supported:
|
||||
|
||||
@ -56,4 +56,4 @@ Please see pages under the "Features" header in the sidebar for details.
|
||||
Contributing
|
||||
</Heading>
|
||||
|
||||
If you'd like to add support for a new keyboard shield, head over to the [New Keyboard Shield](development/new-shield.md) documentation and note the [clean room design requirements](development/clean-room.md).
|
||||
If you'd like to add support for a new keyboard shield, head over to the [New Keyboard Shield](development/new-shield.mdx) documentation and note the [clean room design requirements](development/clean-room.md).
|
||||
|
||||
@ -15,21 +15,21 @@ ZMK is currently missing some features found in other popular firmware. This tab
|
||||
| :------ | :----------- | :------------------- | :--------- |
|
||||
|
||||
| **Feature** | ZMK | BlueMicro | QMK |
|
||||
| ---------------------------------------------------------------------------------------------------------------------------------- | :-: | :-------: | :-: |
|
||||
| ----------------------------------------------------------------------------------------------------------------------------------- | :-: | :-------: | :-: |
|
||||
| Low Latency BLE Support | ✅ | ✅ | |
|
||||
| Multi-Device BLE Support | ✅ | | |
|
||||
| [USB Connectivity](behaviors/outputs.md) | ✅ | ✅ | ✅ |
|
||||
| User Configuration Repositories | ✅ | | |
|
||||
| Split Keyboard Support | ✅ | ✅ | ✅ |
|
||||
| [Keymaps and Layers](behaviors/layers.md) | ✅ | ✅ | ✅ |
|
||||
| [Hold-Tap](behaviors/hold-tap.md) (which includes [Mod-Tap](behaviors/mod-tap.md) and [Layer-Tap](behaviors/layers.md/#layer-tap)) | ✅ | ✅ | ✅ |
|
||||
| [Tap-Dance](behaviors/tap-dance.md) | ✅ | ✅[^2] | ✅ |
|
||||
| [Hold-Tap](behaviors/hold-tap.mdx) (which includes [Mod-Tap](behaviors/mod-tap.md) and [Layer-Tap](behaviors/layers.md/#layer-tap)) | ✅ | ✅ | ✅ |
|
||||
| [Tap-Dance](behaviors/tap-dance.mdx) | ✅ | ✅[^2] | ✅ |
|
||||
| [Keyboard Codes](codes/index.mdx#keyboard) | ✅ | ✅ | ✅ |
|
||||
| [Media](codes/index.mdx#media-controls) & [Consumer](codes/index.mdx#consumer-controls) Codes | ✅ | ✅ | ✅ |
|
||||
| [Encoders](features/encoders.md) | ✅ | ✅ | ✅ |
|
||||
| [Display Support](features/displays.md)[^1] | 🚧 | 🚧 | ✅ |
|
||||
| [RGB Underglow](features/underglow.md) | ✅ | ✅ | ✅ |
|
||||
| [Backlight](features/backlight.md) | ✅ | ✅ | ✅ |
|
||||
| [Backlight](features/backlight.mdx) | ✅ | ✅ | ✅ |
|
||||
| One Shot Keys | ✅ | ✅ | ✅ |
|
||||
| [Combo Keys](features/combos.md) | ✅ | | ✅ |
|
||||
| [Macros](behaviors/macros.md) | ✅ | ✅ | ✅ |
|
||||
|
||||
@ -30,7 +30,7 @@ macOS 13.0 (Ventura) Finder may report an error code 100093 when copying `<firmw
|
||||
### CMake Error
|
||||
|
||||
An error along the lines of `CMake Error at (zmk directory)/zephyr/cmake/generic_toolchain.cmake:64 (include): include could not find load file:` during firmware compilation indicates that the Zephyr Environment Variables are not properly defined.
|
||||
For more information, click [here](../docs/development/setup.md#environment-variables).
|
||||
For more information, click [here](../docs/development/setup.mdx#environment-variables).
|
||||
|
||||
### West Build Errors
|
||||
|
||||
|
||||
@ -3,8 +3,8 @@ title: Installing ZMK
|
||||
sidebar_label: Installing ZMK
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
Unlike other keyboard firmwares, ZMK Firmware has been built from the ground up to allow users to manage
|
||||
their own keyboard configurations, including keymaps, specific hardware details, etc. all outside of the
|
||||
@ -106,7 +106,7 @@ Pick an keyboard:
|
||||
:::note For a keyboard not in the included list:
|
||||
If you are building firmware for a new keyboard that is not included in the built-in
|
||||
list of keyboards, you can choose any keyboard from the list that is similar to yours (e.g. in terms of unibody/split and [onboard controller](hardware.mdx#onboard)/[composite](hardware.mdx#composite)) to generate the repository,
|
||||
and edit / add necessary files. You can follow the [new shield guide](development/new-shield.md) if you are adding support for a composite keyboard.
|
||||
and edit / add necessary files. You can follow the [new shield guide](development/new-shield.mdx) if you are adding support for a composite keyboard.
|
||||
:::
|
||||
|
||||
### MCU Board Selection
|
||||
Loading…
Reference in New Issue
Block a user