forked from kofal.net/zmk
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
@@ -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
|
||||
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>);
|
||||
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>
|
||||
);
|
||||
|
||||
## 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
|
||||
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>);
|
||||
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>
|
||||
);
|
||||
|
||||
## 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:
|
||||
|
||||
@@ -140,7 +140,7 @@ endif
|
||||
|
||||
## Shield Overlays
|
||||
|
||||
<InterconnectTabs items={Metadata}/>
|
||||
<InterconnectTabs items={Metadata} />
|
||||
|
||||
To use GPIO pins that are not part of the interconnects as described above, you can use the GPIO labels that are specific to each controller type.
|
||||
For instance, pins numbered `PX.Y` in nRF52840-based boards can be referred to via `&gpioX Y` labels.
|
||||
@@ -374,7 +374,7 @@ Each keyboard should provide a default keymap to be used when building the firmw
|
||||
|
||||
Here is an example simple keymap for the Kyria, with only one layer:
|
||||
|
||||
<KeymapExampleFile/>
|
||||
<KeymapExampleFile />
|
||||
|
||||
:::note
|
||||
The two `#include` lines at the top of the keymap are required in order to bring in the default set of behaviors to make them available to bind, and to import a set of defines for the key codes, so keymaps can use parameters like `N2` or `K` instead of the raw keycode numeric values.
|
||||
@@ -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
|
||||
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>);
|
||||
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>
|
||||
);
|
||||
|
||||
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>
|
||||
|
||||
Reference in New Issue
Block a user