Skip to content

pqrs-org/KE-complex_modifications

Repository files navigation

Build Status License

KE-complex_modifications

complex_modifications for Karabiner-Elements.

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

complex_modifications documents

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
    },

    You can use the tag <button>⇧Shift</button> to make a nice ⇧Shift in your html.

  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 all

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