README.md

KE-complex_modifications

complex_modifications for Karabiner-Elements.

https://ke-complex-modifications.pqrs.org/

complex_modifications documents

• karabiner.json Reference Manual
  • Typical complex_modifications examples
  • complex_modifications manipulator definition

How to add your rules

Follow the steps below to create a PR and add your settings!

1. Fork this repository on GitHub.

2. Clone the repository in Terminal.

   git clone --depth 1 https://github.com/{your_account}/KE-complex_modifications.git
   cd KE-complex_modifications
   git submodule update --init --recursive --depth 1

3. Create a git branch in Terminal.

   git switch -c my-settings

4. Put a JSON generator file (.js) into src/json. (Or put a .json file directly into public/json directory.)

5. (Optional) Update public/groups.json if you want to add your rules to a particular category.

   Add the following entry into public/groups.json.

   {
       "path": "json/your_awesome_configuration.json", // required
       "extra_description_path": "extra_descriptions/your_awesome_configuration.html" // optional
   },

6. Run make command in Terminal to validate your files.
   If you placed a generator file into src/json, json file will be generated in the public/json by this command.

   make

   If there is a problem, an error message is displayed. Fix your files until no errors are shown.

   "../public/json/personal_tekezo.json": `Personal rules (@tekezo) (rev 47)` error: `to` entry error: `key_code` error: unknown key_code: `"space"`
   make[1]: *** [all] Error 1
   make: *** [all] Error 2
   

7. Test your files

   Copy a json file to ~/.config/karabiner/assets/complex_modifications.

   cp public/json/your_awesome_configuration.json ~/.config/karabiner/assets/complex_modifications

   Import rules from Karabiner-Elements Settings > Complex Modifications > Rules > Add rule.

8. (Optional) Test your files on local web server.

   Run local web server by the following command in Terminal.

   make server

   Then open http://localhost:8000.

9. Run git commit and git push in Terminal.

   git add -A
   git commit -m 'your commit message'
   git push --set-upstream origin my-settings

10. Create a PR on GitHub.

Sync your fork

To update your previously forked repositories, run the following command in Terminal.

Run only once

git remote add upstream https://github.com/pqrs-org/KE-complex_modifications.git

Run every time

# switch to main branch
git switch main

# fetch upstream
git fetch --all --prune --prune-tags

# update local repository
git reset --hard upstream/main

# update submodules
git submodule update --init --recursive

# clean files
git clean -x -d -f .

# update GitHub repository
git push

Notes on creating your generators

The code in src/json/*.js is executed by Duktape, which is built into the Karabiner-Elements's command line interface ( karabiner_cli).

Unlike the latest Node.js, the basic language specification is ES5.1, so the following features cannot be used.

• let (const is specially supported)
• Arrow functions
• Default parameters
• Spread (...) syntax
• Template literals

Examples

There are many existing codes. Here are some of the more distinctive ones among them.

• Use the predefined list of bundle identifiers in frontmost_application_if.
  • capslock_shift_copy_paste.json.js
• Generate remappings from a list of characters
  • colemak_layout.json.js
• Include file from another file
  • personal_thooams.json.js
  • control_backspace_to_function_backspace.json.js
• Generate rules from key combinations
  • matias_ergo_pro.json.js