> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jylhis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Keyboard & Input Methods

> Configure keyboard layouts, variants, IMEs, and XKB options

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):

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

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

```nix theme={}
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

```nix theme={}
marchyo.keyboard.layouts = [
  "us"
  "fi"
  "de"
];
```

### Layouts with variants

```nix theme={}
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:

```nix theme={}
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).

```nix theme={}
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` = `é`).

```nix theme={}
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:

```nix theme={}
marchyo.keyboard.autoActivateIME = false;
```

### Manual IME toggle

Configure a key to manually toggle IME on/off:

```nix theme={}
marchyo.keyboard.imeTriggerKey = [ "Super+I" ];   # Default
```

## Full example

```nix theme={}
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

1. **NixOS (`services.xserver.xkb`)** — Basic layout codes and variants are applied to the console/TTY for fallback support outside the graphical environment.
2. **Hyprland (`home.keyboard`)** — Layout and XKB options are passed to Hyprland's input configuration.
3. **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             |