This document describes Miryoku KMonad only. For Miryoku documentation, implementations, and discussions and support, see Miryoku.
Miryoku KMonad can be used on any keyboard connected to a Linux, Mac, or Windows host. Generate a personalised KMonad config file locally, or via GitHub Actions workflows without use of a local build environment and optionally without editing any files. Then run KMonad with the generated config file. Mappings for row-staggered keyboards can be selected to map an ortho split layout, with or without reverse column angle, or use the lite mapping to keep the traditional home positions and add only home row mods and the Nav layer. The Mouse layer is using mouse keys on the host. The implementation uses a macro processor to enhance the KMonad config file format, and the makefile can also be used with other keymaps.
Generate a personalised KMonad config file.
make # defaults make MIRYOKU_ALPHAS=QWERTY MIRYOKU_NAV=INVERTEDT MIRYOKU_CLIPBOARD=WIN MIRYOKU_LAYERS=FLIP MIRYOKU_MAPPING=LITE MIRYOKU_KMONAD_OS=WIN # custom
A config file can be generated via GitHub Actions workflows without use of a local build environment.
First log in to GitHub, fork the Miryoku KMonad repository, and enable workflows.
To access a workflow, visit the Actions tab and select the workflow. To download the config file from a workflow run, select the workflow, select the workflow run, select the desired Artifacts, and unzip the downloaded zip file.
Workflow files are in .github/workflows.
Copy the Build workflow file, edit the
name value, and edit and add options and values as desired. Select Run workflow, select the Branch if desired, and activate Run workflow.
Options are specified in the
with section and are of the following form.
For multiple values per option use the following form, and a matrix build will be performed for each combination of values across all options.
layers options correspond to the alternative layout options. The
mapping option corresponds to the alternative mapping options. The
kmonad_os option corresponds to the operating system option. Options are given in the documentation in the form
MIRYOKU_OPTION=VALUE. To use here, convert to the form specified above. Use
default to represent the default value. Values for these six options are case-insensitive. See the Build All workflow file for all supported values.
config options can be used to specify values to be appended to
custom_config.h, respectively. Separate multiple lines with
The Test workflow is not applicable when using a Build workflow and should be prevented from running on push by deleting the push line in .github/workflows/test.yml.
Build Inputs Workflow
The Build Inputs workflow can be used without editing workflow files. Select Run workflow, select the Branch and fill out the form as desired, and activate Run workflow.
Options are specified by entering values directly in the corresponding field. Multiple comma separated values can be entered per option and a matrix build will be performed for each combination of values across all options.
Miryoku Clipboard, and
Miryoku Layers options correspond to the alternative layout options. The
Miryoku Mapping option corresponds to the alternative mapping options. The
Miryoku KMonad OS option corresponds to the operating system option. Options are given in the documentation in the form
MIRYOKU_OPTION=VALUE. To use here, enter the
value in the corresponding
Miryoku Option field. Use
default to represent the default value. Values for these six options are case-insensitive.
custom_config.h options can be used to specify values to be appended to the corresponding files. Join multiple lines with
Note that the current binary release for linux (v0.4.1) does not support specifying the keyboard device on the command line. If using that release you will need to edit the config file to specify the keyboard device or create a symlink.
From the src/build directory, run KMonad with the generated config file as follows.
kmonad miryoku_kmonad.kbd # linux, edited config file or symlink kmonad miryoku_kmonad.kbd -i 'device-file "DEVICE"' # linux, keyboard device DEVICE kmonad miryoku_kmonad.kbd # mac, all keyboards kmonad miryoku_kmonad.kbd -i 'iokit-name "PRODUCT"' # mac, keyboard with product string PRODUCT kmonad miryoku_kmonad.kbd # windows
An angled ortho split layout is mapped onto the row-staggered keyboard. The rows are moved up to better position the thumb keys, the hands are separated as much as possible, and the left hand column angle is reversed to reduce ulnar deviation of the wrists.
No Reverse Angle
As default but without the reverse column angle.
This is a hybrid mapping keeping the traditional home positions. Only the 3x10 alphas plus space as primary thumb key are mapped. The remaining keys are the same as the native keyboard but with semicolon in place of quote. This enables the selection of alternative alphas, and use of home row mods and the finger part of the Nav layer. Other than with
MIRYOKU_LAYERS=FLIP, backspace, enter, delete, tab, and escape are also mapped as the corresponding thumb keys.
This is the default.
Additional and Experimental Features
The Mouse layer is using mouse keys on the host.
- X11: https://en.wikipedia.org/wiki/Mouse_keys
- Mac: https://support.apple.com/en-au/guide/mac-help/mh27469/mac
- Windows: https://support.microsoft.com/en-us/windows/use-mouse-keys-to-move-the-mouse-pointer-9e0c72c8-b882-7918-8e7b-391fd62adf33
The config file source is src/miryoku_kmonad.kbd.cpp. The generated config file is src/build/miryoku_kmonad.kbd and is produced by src/makefile. The C preprocessor (
cpp) is used to enhance the KMonad config file format, adding includes, conditionals, constants, and functions. Characters not preserved by
cpp are substituted by
Use With Other Keymaps
The makefile can also be used with other keymaps. A file with a
.kbd.cpp extension in src will be converted to the corresponding file with a
.kbd extension under src/build. The following keycodes should be substituted in the source as indicated.