Miryoku KMonad

Miryoku is an ergonomic, minimal, orthogonal, and universal keyboard layout. Miryoku KMonad is the Miryoku implementation for KMonad.

This document describes Miryoku KMonad only. For Miryoku documentation, implementations, and discussions and support, see Miryoku.

Overview

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.

Building

Generate a personalised KMonad config file.

Local Builds

Requires make, sh, cpp, and sed.

First cd to the src directory then build with make. The generated config file is src/build/miryoku_kmonad.kbd.

To select alternative layout, mapping, and other options, append them to the make command line.

make # defaults
make MIRYOKU_ALPHAS=QWERTY MIRYOKU_EXTRA=COLEMAKDH MIRYOKU_TAP=QWERTY MIRYOKU_NAV=INVERTEDT MIRYOKU_CLIPBOARD=WIN MIRYOKU_LAYERS=FLIP MIRYOKU_MAPPING=LITE MIRYOKU_KMONAD_OS=WIN # custom

Workflow Builds

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.

Build Workflow

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.

option: '["value"]'

For multiple values per option use the following form, and a matrix build will be performed for each combination of values across all options.

option: '["value1","value2"]'

The alphas, nav, clipboard, and 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.

The rules and config options can be used to specify values to be appended to custom_rules.mk and custom_config.h, respectively. Separate multiple lines with \n.

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.

The Miryoku Alphas, Miryoku Nav, 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.

The custom_rules.mk and custom_config.h options can be used to specify values to be appended to the corresponding files. Join multiple lines with \n.

Running KMonad

First install KMonad and generate the config file.

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

Mapping

Default

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

MIRYOKU_MAPPING=NOREVERSEANGLE

As default but without the reverse column angle.

Lite

MIRYOKU_MAPPING=LITE

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.

Tap

MIRYOKU_MAPPING=TAP

Corresponds to the tap functions of the Miryoku Base layer with default layout options. For use with remappable keyboards.

Kinesis Advantage

MIRYOKU_MAPPING=KINESIS_ADVANTAGE

Other Options

Operating System

Linux

This is the default.

Mac

MIRYOKU_KMONAD_OS=MAC

Windows

MIRYOKU_KMONAD_OS=WIN

Additional and Experimental Features

Mouse Keys

The Mouse layer is using mouse keys on the host.

Implementation

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 sed.

Macros are included from src/miryoku.h. Layer data is generated by Miryoku Babel and included from files in src/miryoku_babel.

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.

Keycode	Substitute
‘	U_QUOT
“	U_DQUO
,	U_COMM
\(	U_LPRN
\)	U_RPRN

deweyx/miryoku_kmonad