zephyr
/
zmk
mirror of https://github.com/zmkfirmware/zmk.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

* 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
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 120 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

185
docs/docs/user-setup.mdx
View File

@ -7,20 +7,19 @@ import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem"; import TabItem from "@theme/TabItem";
export const OsTabs = (props) => ( export const OsTabs = (props) => (
<Tabs <Tabs
groupId="operating-system" groupId="operating-system"
queryString queryString
defaultValue="linux" defaultValue="linux"
values={[ values={[
{ label: "Linux", value: "linux" }, { label: "Linux", value: "linux" },
{ label: "Windows", value: "win" }, { label: "Windows", value: "win" },
{ label: "Mac OS", value: "mac" } { label: "macOS", value: "mac" },
]} ]}
> >
{/* eslint-disable-next-line */} {/* eslint-disable-next-line */}
{props.children} {props.children}
</Tabs> </Tabs>
); );
Unlike other keyboard firmwares, ZMK Firmware has been built from the ground up to allow users to manage Unlike other keyboard firmwares, ZMK Firmware has been built from the ground up to allow users to manage
@ -54,10 +53,9 @@ Following the steps in this guide, you will:
You will need to install a few tools before you can get started. You will need to install a few tools before you can get started.
Many instructions in this guide use commands that need to be run in a terminal application. Many instructions in this guide use commands that need to be run in a terminal application. On most operating systems, the program is simply named "Terminal".
- On Windows, use [Windows Terminal](https://apps.microsoft.com/detail/9n0dx20hk701) or PowerShell. On Windows, get [Windows Terminal](https://apps.microsoft.com/detail/9n0dx20hk701) from the Microsoft Store if it isn't already installed.
- On other operating systems, the terminal program is usually just named "Terminal".
### Install Git ### Install Git
@ -67,7 +65,7 @@ Open a terminal and run the following command. If Git is already installed, it w
git --version git --version
``` ```
If it gives an error instead, install Git from https://git-scm.com/install/. Close and re-open your terminal and run the `git --version` command again to check if it installed correctly. If it prints an error instead, install Git from https://git-scm.com/install/. Close and reopen your terminal and run the `git --version` command again to check if it installed correctly.
:::note :::note
This guide will have you run several more `git` commands later. If you aren't familiar with Git, check out [Learn The Basics Of Git In Under 10 Minutes](https://www.freecodecamp.org/news/learn-the-basics-of-git-in-under-10-minutes-da548267cc91/) to help you get started. This guide will have you run several more `git` commands later. If you aren't familiar with Git, check out [Learn The Basics Of Git In Under 10 Minutes](https://www.freecodecamp.org/news/learn-the-basics-of-git-in-under-10-minutes-da548267cc91/) to help you get started.
@ -91,132 +89,131 @@ gh auth login
Create a [personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) and make sure to create it with the "workflow" scope option selected. Create a [personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) and make sure to create it with the "workflow" scope option selected.
When running `git` commands later in this guide, Git will ask for your username and password. Enter your GitHub username, but **do not enter your password**. Instead, paste your access token for the password. You won't be able to see the token again after you create it, so keep the page open until you've done this and/or copy it to a secure location. If you lose the token, simply create another one. When running `git` commands later in this guide, Git will ask for your username and password. Enter your GitHub username, but **do not enter your password**. Instead, paste your access token where it asks for the password. You won't be able to see the token again after you create it, so keep the page open until you've done this and/or copy it to a secure location. If you lose the token, simply create another one.
### Install Python and pipx ### Install uv
ZMK CLI requires Python version 3.10 or above. [uv](https://github.com/astral-sh/uv) is a Python package manager which can install ZMK CLI and a supported version of Python if necessary. The instructions for installing uv differ depending on your operating system. Select the tab for your OS below.
There are several ways you can install ZMK CLI, but for simplicity, this guide will use [pipx](https://pipx.pypa.io/stable/). (If you are already familiar with another Python package manager such as [uv](https://github.com/astral-sh/uv), you can install the `zmk` package with it instead, but that will not be covered in this guide.) If installation fails, see [https://docs.astral.sh/uv/getting-started/installation/](https://docs.astral.sh/uv/getting-started/installation/) for more detailed instructions and alternative installation methods.
The instructions for installing Python and pipx differ depending on your operating system. <details>
<summary>Other package managers</summary>
ZMK CLI can also be installed with other Python package managers such as [pipx](https://pipx.pypa.io/stable/). If you have a different package manager you prefer, install the ["zmk" package](https://pypi.org/project/zmk/) and skip to [Config Repo Setup](#config-repo-setup).
</details>
<OsTabs> <OsTabs>
<TabItem value="linux"> <TabItem value="linux">
Python comes preinstalled on most Linux distributions, but pipx needs to be installed separately. In case Python isn't already installed, this guide will have you install both. Pick the commands relevant to the distribution you are using: Open a terminal and run the following command:
#### Ubuntu 23.04 or above ```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
```
If you get an error like "curl: command not found", try using wget:
```sh
wget -qO- https://astral.sh/uv/install.sh | sh
```
If that doesn't work either, install [curl](https://curl.se/) and try again. For example, on Ubuntu and other Debian-based Linux distributions, run:
```sh ```sh
sudo apt update sudo apt update
sudo apt install python3 pipx sudo apt install curl
pipx ensurepath curl -LsSf https://astral.sh/uv/install.sh | sh
``` ```
#### Ubuntu 22.04 If the install script prints the following, close and reopen your terminal.
```sh
sudo apt update
sudo apt install python3
python3 -m pip install --user pipx
python3 -m pipx ensurepath
``` ```
To add $HOME/.local/bin to your PATH, either restart your shell or run:
#### Ubuntu 20.04 source $HOME/.local/bin/env (sh, bash, zsh)
source $HOME/.local/bin/env.fish (fish)
Ubuntu 20.04 comes with an older version of Python. You can install Python 3.10 from the deadsnakes PPA with the following commands:
```sh
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.10
python3.10 -m pip install --user pipx
python3.10 -m pipx ensurepath
``` ```
You will then need to replace `python3` with `python3.10` in the rest of the installation instructions.
#### Fedora 35 or above
```sh
sudo dnf install python3 pipx
pipx ensurepath
```
If you have an older version of Fedora, you will need to update your operating system to a newer version or [build Python from source](https://docs.python.org/3/using/unix.html#building-python).
#### Other distributions
Install Python 3 and pipx using your distribution's package manager. If there is no package for pipx, install it with `pip` after installing Python:
```sh
python3 -m pip install --user pipx
python3 -m pipx ensurepath
```
Check the version of Python you installed:
```sh
python3 --version
```
If this prints a version less than 3.10, you will need to update your operating system to a newer version or [build Python from source](https://docs.python.org/3/using/unix.html#building-python).
</TabItem> </TabItem>
<TabItem value="win"> <TabItem value="win">
Open https://www.python.org/downloads/ and select "Download Python install manager". Run the installer, then open a terminal and run the following command to install the latest version of Python 3: Open a terminal and run the following command:
```sh ```sh
py install 3 winget install --id astral-sh.uv -e --source winget
``` ```
Next, install pipx: If this prints the text that is highlighted below, close and reopen your terminal.
```sh ```
py -m pip install --user pipx // highlight-next-line
py -m pipx ensurepath Path environment variable modified; restart your shell to use the new value.
Command line alias added: "uvx"
Command line alias added: "uv"
Command line alias added: "uvm"
Successfully installed
``` ```
</TabItem> </TabItem>
<TabItem value="mac"> <TabItem value="mac">
First, install Homebrew from https://brew.sh/. Next, open a terminal and run: Open a terminal and run the following command:
```sh ```sh
brew install pipx curl -LsSf https://astral.sh/uv/install.sh | sh
pipx ensurepath
``` ```
This should automatically install Python 3 if it is missing. If the install script prints the following, close and reopen your terminal.
```
To add $HOME/.local/bin to your PATH, either restart your shell or run:
source $HOME/.local/bin/env (sh, bash, zsh)
source $HOME/.local/bin/env.fish (fish)
```
</TabItem> </TabItem>
</OsTabs> </OsTabs>
### Verify pipx Install
Close and re-open your terminal, then run:
```sh
pipx --version
```
It should print a version number. If not, go back to the previous step and make sure you installed pipx correctly. You can also try logging out of your computer and logging back in to make sure any environment variables changes made during installation take effect.
### Install ZMK CLI ### Install ZMK CLI
Finally, we'll install ZMK CLI. Open a terminal and run: Finally, we'll install ZMK CLI. Open a terminal and run:
```sh ```sh
pipx install zmk uv tool install zmk
zmk --version
``` ```
It should print a version number if everything installed correctly. <details>
<summary>I get an "executable already exists" error</summary>
On Linux, you may get an error saying you need to install another package such as `python3.10-venv`. If so, follow the instructions in the error message, then try the above commands again. Earlier versions of this guide used pipx. If you get an error like this...
```
error: Executable already exists: zmk.exe (use `--force` to overwrite)
```
...run the following commands to remove the pipx version and reinstall it with uv:
```sh
python3 -m pipx uninstall zmk
uv tool install zmk
```
</details>
This will likely print a message like ``warning: `/home/username/.local/bin` is not on your PATH``. To fix that, run:
```sh
uv tool update-shell
```
Close and reopen your terminal to apply the changes, then run the following command. It should print a version number if everything installed correctly.
```sh
zmk --version
```
## Config Repo Setup ## Config Repo Setup
@ -237,22 +234,22 @@ Then, [skip to the next step](#add-a-keyboard).
</details> </details>
Open a terminal and use the `cd` command to move to a folder where you'd like to place the ZMK files (it will create a `zmk-config` subfolder in this location), then run `zmk init`. For example: Open a terminal and use the `cd` command to move to a folder where you'd like to place the ZMK files (it will create a new folder in this location), then run `zmk init`. For example:
```sh ```sh
cd ~/Documents cd ~/Documents
zmk init zmk init
``` ```
Follow the instructions it gives you. If you already have a ZMK config repo on GitHub, you can enter its URL when prompted, for example: Follow the instructions it gives you. If you already have a ZMK config repo on GitHub, select "Clone an existing repo" and enter its URL when prompted, for example:
``` ```
Repository URL: https://github.com/myusername/zmk-config Repository URL: https://github.com/myusername/zmk-config
``` ```
Otherwise, leave this first prompt blank and press <kbd>Enter</kbd>, and it will walk you through creating a new repo. Otherwise, select "Create a new ZMK config repo", and follow the instructions to create a new repo.
Once you finish following all the instructions, you will have a copy of the repo stored on your computer. All `zmk` commands will run on this repo (unless the working directory is inside a different repo). If you ever forget where the repo is located, you can run `zmk cd` to find it. After this finishes, you will have a copy of the repo stored on your computer. All `zmk` commands will run on this repo (unless the working directory is inside a different repo). If you ever forget where the repo is located, you can run `zmk cd` to find it.
### Add a Keyboard ### Add a Keyboard
@ -328,7 +325,7 @@ The text after `-m` is the "commit message", which gives a name to the commit. T
:::warning :::warning
If the `git push` command asks you for a username and password, enter your GitHub username, but **do not enter your password**. Instead, paste your access token for the password. (Go back to the [GitHub account setup instructions](#set-up-a-github-account) if you need to create a token.) If the `git push` command asks you for a username and password, enter your GitHub username, but **do not enter your password**. Instead, paste your access token where it asks for the password. (Go back to the [GitHub account setup instructions](#set-up-a-github-account) if you need to create a token.)
::: :::
@ -346,11 +343,17 @@ Or, you can manually open your GitHub repository in your browser and click the "
![](./assets/user-setup/github-actions-link.png) ![](./assets/user-setup/github-actions-link.png)
Once you have loaded the Actions tab, select the top build from the list. Once you load it, the right side panel will include Once you have loaded the Actions tab, select the top build from the list. If the build was successful, the right side panel will include
a link to download the `firmware` upload: a link to download the `firmware` upload:
![](./assets/user-setup/firmware-archive.png) ![](./assets/user-setup/firmware-archive.png)
:::info[Fixing build errors]
If you see a red X instead of a link to download the firmware, the build failed, likely due to an error in your repo. See the [troubleshooting page](./troubleshooting/building-issues.md) for help fixing the error. After making changes, [commit and push](#commit-and-push-to-github) again and GitHub will start a new build.
:::
Once downloaded, extract the zip and you can verify it should contain one or more `.uf2` or `.hex` files, which contain the firmware you need to write to your keyboard. Once downloaded, extract the zip and you can verify it should contain one or more `.uf2` or `.hex` files, which contain the firmware you need to write to your keyboard.
### Flash UF2 Files ### Flash UF2 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. 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 ## 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`. 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 ### Initialize a Repository

25
docs/src/css/custom.css
View File

@ -7,16 +7,11 @@
/* You can override the default Infima variables here. */ /* You can override the default Infima variables here. */
:root { :root {
--ifm-color-primary: #026fc5;
--ifm-color-primary-dark: #0264b1;
--ifm-color-primary-darker: #025ea7;
--ifm-color-primary-darkest: #014e8a;
--ifm-color-primary-light: #027ad9;
--ifm-color-primary-lighter: #0280e3;
--ifm-color-primary-lightest: #0690fc;
--ifm-code-font-size: 95%; --ifm-code-font-size: 95%;
--docusaurus-highlighted-code-line-bg: rgb(0 0 0 / 8%); --docusaurus-highlighted-code-line-bg: rgb(0 0 0 / 8%);
--docusaurus-highlighted-code-line-border-width: 5px;
--docusaurus-highlighted-code-line-border-color: var(--ifm-color-primary);
} }
[data-theme="dark"] { [data-theme="dark"] {
@ -38,10 +33,18 @@
background-color: var(--ifm-navbar-link-hover-color); background-color: var(--ifm-navbar-link-hover-color);
} }
.docusaurus-highlight-code-line { .theme-code-block .theme-code-block-highlighted-line {
display: block; /* Line numbers have a solid color background which would cover the highlighted line */
margin: 0 calc(-1 * var(--ifm-pre-padding)); --ifm-pre-background: transparent;
padding: 0 var(--ifm-pre-padding);
/* Add a colored block to the left of any highlighted lines */
border-left: var(--docusaurus-highlighted-code-line-border-width) solid
var(--docusaurus-highlighted-code-line-border-color);
padding-left: calc(
var(--ifm-pre-padding) -
var(--docusaurus-highlighted-code-line-border-width)
);
} }
.video-container { .video-container {