Keyboard & Input Methods

Marchyo provides a unified way to configure keyboard layouts, variants, input methods (IMEs), and XKB options across the system (TTY/console) and the desktop environment (Hyprland + fcitx5).

Defaults

Out of the box:

layouts = [ { layout = "us"; variant = "altgr-intl"; } "fi" ]
options = [ "grp:win_space_toggle" ] (Super+Space switches layout/IME)
composeKey = "menu"

The altgr-intl variant (“English (US, intl., AltGr dead keys)”) behaves like a plain US layout for the unmodified keys — ', ", `, ~, ^ produce their normal characters, not dead keys. The international characters live behind the AltGr modifier (Right Alt).

Typography on AltGr

Sequence	Result
`AltGr` + `-`	`–` (en dash)
`AltGr` + `Shift` + `-`	`—` (em dash)
`AltGr` + `9` / `AltGr` + `0`	`‘` / `’` (curly single quotes)
`AltGr` + `Shift` + `9` / `AltGr` + `Shift` + `0`	`“` / `”` (curly double quotes)
`AltGr` + `[` / `AltGr` + `]`	`«` / `»` (guillemets)
`AltGr` + `5`	`€`
`AltGr` + `4`	`¤` (currency)

The Menu key acts as Compose for everything else (Menu then ' then e → é, Menu then - - - → —, etc.). If you want the stronger dead-key behavior of plain us(intl) (where ', ", `, ~, ^ wait for a follow-up letter):

marchyo.keyboard.layouts = [ { layout = "us"; variant = "intl"; } "fi" ];

If you have no Menu key, point Compose elsewhere (or disable it):

marchyo.keyboard.composeKey = "caps";   # or "rwin", "rctrl", or null

Layouts

The marchyo.keyboard.layouts option accepts a list of layouts. Each can be a simple string or an attribute set for advanced configuration.

Simple layouts

marchyo.keyboard.layouts = [
  "us"
  "fi"
  "de"
];

Layouts with variants

marchyo.keyboard.layouts = [
  "us"
  { layout = "us"; variant = "intl"; }   # US International with dead keys
  { layout = "us"; variant = "dvorak"; }
];

Layouts with input methods

For CJK languages and other complex input, specify an IME:

marchyo.keyboard.layouts = [
  "us"
  { layout = "cn"; ime = "pinyin"; }   # Chinese with Pinyin
  { layout = "jp"; ime = "mozc"; }     # Japanese with Mozc
  { layout = "kr"; ime = "hangul"; }   # Korean with Hangul
];

When an entry includes ime, the input method engine is automatically activated when you switch to that layout.

Available IMEs

IME	Language	Required package
`"pinyin"`	Chinese	`fcitx5-chinese-addons`
`"mozc"`	Japanese	`fcitx5-mozc`
`"hangul"`	Korean	`fcitx5-hangul`
`"unicode"`	Unicode picker	—

Required packages are installed automatically when an IME is specified.

Layout attribute set options

Option	Type	Default	Description
`layout`	`string`	—	Keyboard layout code (e.g., `"us"`, `"fi"`, `"cn"`)
`variant`	`string`	`""`	Layout variant (e.g., `"intl"`, `"dvorak"`)
`ime`	`string` or `null`	`null`	Input method engine
`label`	`string` or `null`	`null`	Display label (auto-generated if null)

Keyboard switching

XKB options

Use marchyo.keyboard.options for standard XKB options. Default: ["grp:win_space_toggle"] (Super+Space to switch layouts).

marchyo.keyboard.options = [
  "grp:win_space_toggle"   # Super+Space to switch inputs
  "ctrl:swapcaps"          # Swap Caps Lock and Left Control
  "caps:escape"            # Map Caps Lock to Escape
];

Compose key

The compose key lets you type special characters via key sequences (e.g., Compose + ' + e = é).

marchyo.keyboard.composeKey = "menu";  # Default: Menu key

Value	Key
`"menu"`	Menu key (default)
`"ralt"`	Right Alt — avoid when using `us(altgr-intl)` or `us(intl)` (it needs Right Alt as AltGr)
`"rwin"`	Right Super/Windows
`"caps"`	Caps Lock
`null`	Disable compose key

IME behavior

Auto-activation

By default, switching to a layout with an IME activates it automatically. Disable this to require manual activation:

marchyo.keyboard.autoActivateIME = false;

Manual IME toggle

Configure a key to manually toggle IME on/off:

marchyo.keyboard.imeTriggerKey = [ "Super+I" ];   # Default

Full example

marchyo.keyboard = {
  layouts = [
    { layout = "us"; variant = "altgr-intl"; }
    { layout = "fi"; }
    { layout = "us"; variant = "intl"; }
    { layout = "cn"; ime = "pinyin"; }
    { layout = "jp"; ime = "mozc"; }
  ];
  options = [ "grp:win_space_toggle" ];
  composeKey = "menu";
  autoActivateIME = true;
  imeTriggerKey = [ "Super+I" ];
};

How it works

NixOS (services.xserver.xkb) — Basic layout codes and variants are applied to the console/TTY for fallback support outside the graphical environment.
Hyprland (home.keyboard) — Layout and XKB options are passed to Hyprland’s input configuration.
fcitx5 — Acts as the authoritative input manager in the graphical environment, managing layouts, IMEs, and layout switching.

All options reference

Option	Type	Default	Description
`marchyo.keyboard.layouts`	list of strings or attrsets	`[{ layout = "us"; variant = "altgr-intl"; } "fi"]`	Keyboard layouts and input methods
`marchyo.keyboard.options`	list of strings	`["grp:win_space_toggle"]`	XKB keyboard options
`marchyo.keyboard.composeKey`	string or null	`"menu"`	Compose key
`marchyo.keyboard.autoActivateIME`	bool	`true`	Auto-activate IME on layout switch
`marchyo.keyboard.imeTriggerKey`	list of strings	`["Super+I"]`	Manual IME toggle keys

​Defaults

​Typography on AltGr

​Layouts

​Simple layouts

​Layouts with variants

​Layouts with input methods

​Available IMEs

​Layout attribute set options

​Keyboard switching

​XKB options

​Compose key

​IME behavior

​Auto-activation

​Manual IME toggle

​Full example

​How it works

​All options reference