kofal.net/zmk
1
0
Fork 1
mirror of https://github.com/zmkfirmware/zmk.git synced 2026-03-20 04:55:20 -05:00
Code Issues Packages Projects Releases Wiki Activity

fix(docs): Improve ZMK setup instructions (#3209)

Browse Source 
* fix(docs): Improve link and code highlight contrast

Reset the theme's primary colors to the defaults, since the color of
links was a bit too low contrast in the dark theme. The default primary
color is a very similar but slightly lighter shade of blue.

The background color of highlighted lines in code blocks is also fairly
low contrast, but it needs to be in order to keep the text readable. To
add contrast here, we now add a colored block to the left side of a
highlighted line.

* fix(docs): Improve ZMK setup instructions

This makes several improvements to the instructions for installing and
using ZMK CLI:

- Windows Terminal is also named "Terminal", so reworded the terminal
  instructions to not separate Windows from other OSes.

- Specified that Windows Terminal should always be used on Windows, as
  on older installations of Windows, the default terminal when opening
  PowerShell may be the legacy console host, which may not support some
  of the VT sequences used by ZMK CLI.

- Switched from pipx to uv. This eliminates the need for instructions
  on installing Python, as uv will automatically install a supported
  version of Python if needed.

- Updated the instructions for running "zmk init", as ZMK CLI version
  0.4.0 switched from immediately asking for a repo URL to prompting
  the user to select between creating a new repo or cloning an existing
  one first.

- Since for a new user, having a keymap compile successfully on the
  first attempt after modifying it may be the exception rather than the
  norm, added a note about error messages in GitHub actions with a link
  to the troubleshooting page.

Also added instructions for updating ZMK CLI to the latest version on
the ZMK CLI page.
This commit is contained in:
Joel Spadin
2026-01-17 20:00:01 -06:00
committed by GitHub
parent ab46f48dde
commit 354cff9c36
3 changed files with 120 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/docs/zmk-cli.mdx
View File

@@ -7,13 +7,20 @@ ZMK CLI is a command line tool which helps with setting up a ZMK config repo and
See the [ZMK installation guide](user-setup.mdx#prerequisites) for instructions on installing ZMK CLI.
The instructions below contain commands that need to be run in a terminal program. On most operating systems, the program is simply named "Terminal".
On Windows, get [Windows Terminal](https://apps.microsoft.com/detail/9n0dx20hk701) from the Microsoft Store if it isn't already installed.
## Updating ZMK CLI
To update to the latest version of ZMK, run the following command in a terminal:
```sh
uv tool upgrade zmk
```
## Using ZMK CLI
The instructions below contain commands that need to be run in a terminal program.
- On Windows, use [Windows Terminal](https://apps.microsoft.com/detail/9n0dx20hk701) or PowerShell.
- On other operating systems, the terminal program is usually just named "Terminal".
All ZMK CLI commands start with `zmk`. Run `zmk --help` for general usage instructions. For help with a specific subcommand, add `--help` after the subcommand, e.g. `zmk init --help`.
### Initialize a Repository