Getting started guide for relative beginners

[shombando]

Hi @jtroo! Thanks for the great project, I wanted QMK for every keyboard and Kanata fits the need exactly.

I have written a fairly detailed getting started guide for relative beginners in the world of computer customizing. The write up has a focus on not only what to do but why we're doing it and with some background around what these different pieces of configuration mean. My hope is to simplify the first steps for someone without a programming/IT background.

https://shom.dev/start/using-kanata-to-remap-any-keyboard/

I'm not sure how useful it will be for anyone finding themselves looking into such involved topic but if anyone finds it useful or needs more information I'm happy to share.

[jtroo]

Thanks for sharing!

[briandipalma]

Thank you, nice guide 👍

[shombando]

Thanks, I'd be happy to incorporate if you have any feedback!

[briandipalma]

The home row mods link is broken.

[shombando]

Thanks for letting me know, I have fixed it!

[bogorad]

I'd suggest some info on priorities, e.g., first do tap-dance, then chords, then tap-hold. Otherwise, it might get tricky (was for me 😁).

[shombando]

hey @bogorad thanks for the suggestion. I haven't dug into the priorities because I still with tap-hold but I'll look into it and update the article.

[bogorad]

here are some demos.

first, a simple tap-dance:

single f => f
double-tap f => '
triple-tap f => grave

(defsrc a s d f)

(defalias
  bas-a a
  bas-s s
  bas-d d
  bas-f (tap-dance 200 (f ' grv))
)

(deflayer U_BASE
  @bas-a  @bas-s  @bas-d  @bas-f
)

now adding one-shot:
single-tap f => f
double-tap f => temporarily (1 sec or next key) switch to layer U_FUN

(defsrc a s d f)

(defalias
  bas-a a
  bas-s s
  bas-d d
  bas-f (tap-dance 200 (f (one-shot 1000 (layer-while-held U_FUN))))
)

(deflayer U_BASE
  @bas-a  @bas-s  @bas-d  @bas-f
)

(deflayer U_FUN
  f1 f2 f3 f4
)

now add d+f combo/chord:
single f => f
double-tap f => temporarily (1 sec or next key) switch to layer U_FUN
d + f => caps-word for 3 sec

(defsrc a s d f)

;; kba => (k)ey + (b)ase layer + (a)
(defchords bas-chords 300
  (kba            ) a
  (    kbs        ) s
  (        kbd    ) d
  (            kbf) f
  (        kbd kbf) (caps-word 3000)
)

(defalias
  bas-a (chord bas-chords kba)
  bas-s (chord bas-chords kbs)
  bas-d (chord bas-chords kbd)
  bas-f (tap-dance 200 ((chord bas-chords kbf) (one-shot 1000 (layer-while-held U_FUN))))
)

(deflayer U_BASE
  @bas-a  @bas-s  @bas-d  @bas-f
)

(deflayer U_FUN
  f1 f2 f3 f4
)

finally, tap-hold-press:
single f => f
double-tap f => temporarily (1 sec or next key) switch to layer U_FUN
d + f => caps-word for 3 sec
while f is held => shift

(defsrc a s d f)

;; kba => (k)ey + (b)ase layer + (a)
(defchords bas-chords 300
  (kba            ) a
  (    kbs        ) s
  (        kbd    ) d
  (            kbf) (tap-hold-press 200 200 f sft)
  (        kbd kbf) (caps-word 3000)
)

(defalias
  bas-a (chord bas-chords kba)
  bas-s (chord bas-chords kbs)
  bas-d (chord bas-chords kbd)
  bas-f (tap-dance 200 ((chord bas-chords kbf) (one-shot 1000 (layer-while-held U_FUN))))
)

(deflayer U_BASE
  @bas-a  @bas-s  @bas-d  @bas-f
)

(deflayer U_FUN
  f1 f2 f3 f4
)

[briandipalma]

That's very interesting @bogorad where would you use tap-dances and some of these more complicated setups? I'm slowly starting to fill out my configuration so that my standard keyboard is acting more and more like a ZSA Voyager and I use fewer and fewer keys: https://github.com/briandipalma/iac/blob/main/dotfiles/kanata/kanata.kbd but I've yet to try anything like these approaches you outlined above. Everything is on layers and I enable them temporarily. This tap dance approach seems very interesting as a replacement for a symbols layer which at the moment I enable by holding the spacebar which is OK but feels slightly slow.

[bogorad]

Here's my config.

https://github.com/bogorad/miryoku-kanata/blob/main/kanata.kbd

I'm using Kinesis Advantage KB500 (unhacked still) and my config replicates Miryoku, with some changes, most notably when dealing with a second language.

I used to tap-dance letters that didn't fit on the base layer, but eventually moved them to a different layer, it's more efficient in my experience.

I also copied @jtroo 's method of dealing with HRMs+rolls.

Also, my language switching is on a timeout.

[shombando]

here are some demos.
@bogorad That is incredible, thanks for these! I will incorporate them into the guide and credit you and this thread.

I've also been helping someone irc (#kanata on libera.chat) and they need a AltGr layer for lowercase diacritics and a shifted layer for uppercase). I'm sure there might be a better approach but it was a fun puzzle to solve.

H̲ is a two character unicode so I implemented it as a macro (for Linux). What's the idiomatic way to do that?

;; global configuration options
(defcfg
	process-unmapped-keys yes
	log-layer-changes yes
)

;; define keys that will be modified (all keys still processed)
(defsrc
	h j
	lsft ralt rsft
)

;; default/base layer modifications always active
(deflayer default
	_ _
	_ @altGr _
)

;; shifted layer activated by holding Right Alt (ALtGr) key
(deflayer altGr
	@H̲ (unicode Ĵ)
	_ _ _
)

;; shifted layer activated by holding Right Alt (ALtGr) and Shift key
(deflayer S-altGr
	(unicode ẖ) (unicode ĵ)
	(release-layer S-altGr) _ (release-layer S-altGr)
)

;; values used by multiple changes
(defvar
	tap-time 200
	hold-time 250
)

;; remapping between physical keys and functionality
(defalias
	altGr (multi (layer-while-held altGr) (layer-while-held S-altGr))
	0 0
	3 3
	2 2
	H̲ (macro S-h C-S-u @0 @3 @3 @2 spc)
)

Edit: unfortunately code fences don't play nice with , bummer

[jtroo]

What's the idiomatic way to do that?

That's an interesting use case. It turns out you can still use a combining character in the configuration, though I find it messes up my terminal window when I do it.

(defsrc 0)
(deflayer base (macro S-h (unicode  ̲ )))

[shombando]

@jtroo that's interesting... yeah terminal doesn't always play nice with Kanata emitting unicode, neither does the Rust iced UI's text input field.
Good to learn that you can just inline a macro like that, no need to alias it. Thanks!