# How to Configure Custom Patches in custom.yaml Files for Rime Wanxiang

> Learn to configure custom patches in custom.yaml files for Rime Wanxiang. Effortlessly override and extend configurations using a simple patch syntax to personalize your input method.

- Repository: [amzxyz/rime_wanxiang](https://github.com/amzxyz/rime_wanxiang)
- Tags: how-to-guide
- Published: 2026-02-24

---

**To configure custom patches in [`custom.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/custom.yaml) files for the Rime Wanxiang input method, create a file under the `custom/` directory, add a top-level `patch:` key, and define specific configuration overrides or extensions using the `__patch` syntax for tables and direct key assignments for scalar values.**

The [`custom.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/custom.yaml) files in the **amzxyz/rime_wanxiang** repository serve as user-level extension points for the 万象拼音 (Wanxiang Pinyin) Rime schema. These files allow you to modify spelling algebra, page sizes, and module behaviors without editing core schema files. When Rime loads a schema, it merges three configuration layers—upstream defaults, schema defaults, and your custom patches—to produce the final runtime configuration.

## Understanding the Three-Layer Configuration Merge

The Wanxiang schema implements a hierarchical configuration system that processes files in strict order:

1. **Built-in defaults** – [`default.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/default.yaml) contains generic Rime settings including menu size and key bindings.
2. **Schema defaults** – [`wanxiang.schema.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang.schema.yaml) defines the core Wanxiang configuration, including spellers, translators, and filters.
3. **User customizations** – Any `custom/*.custom.yaml` file placed in the schema directory applies final overrides.

The merge is performed by Rime's native patch mechanism. According to the source code in `amzxyz/rime_wanxiang`, only keys explicitly listed in your custom file are modified; all other settings inherit from lower layers unchanged.

## Patch Syntax Strategies

Depending on your goal, you will use one of two syntax patterns: the `__patch` directive for extending tables or direct assignment for replacing values.

### Extending Tables with __patch

When you need to append, prepend, or selectively modify entries in an existing list (such as spelling algebra rules), use the `__patch` sub-key. In [`custom/wanxiang.custom.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/custom/wanxiang.custom.yaml), this appears as:

```yaml
speller/algebra:
  __patch:
    - wanxiang_algebra:/base/全拼   # Appends full-pinyin algebra to existing rules

```

This syntax preserves the base schema's existing algebra entries while adding your specified module from `wanxiang_algebra`.

### Overriding Values Directly

To replace a scalar value or an entire configuration block, omit `__patch` and assign the new value directly. For example, to enforce a maximum candidate page size of 6 (as required by the schema):

```yaml
menu/page_size: 6

```

Similarly, to completely replace the super replacer configuration rather than extend it:

```yaml
super_replacer:
  db_name: lua/replacer
  delimiter: "|"
  types:
    - option: emoji
      mode: append

```

## Configuring Specific Modules

The Wanxiang schema exposes several modular components through the patch system.

### Enabling Super Comments

To activate the comment module and set its display length, override the `super_comment` block. As implemented in the reference configuration:

```yaml
super_comment:
  candidate_length: 2
  corrector_type: "〔comment〕"

```

### Customizing Character Sets

Define whitelist or blacklist filters by patching the `charset` section. This controls which characters appear in your candidate list based on frequency or category filters referenced in the `lua/` directory.

### Disabling Specific Tips

Turn off unwanted tip categories using the `tips` configuration:

```yaml
tips:
  disabled_types: []

```

## Step-by-Step Implementation Workflow

Follow this sequence to apply custom patches safely:

1. **Create the patch file** – Navigate to the `custom/` directory in your Rime user folder and create or edit [`wanxiang.custom.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang.custom.yaml).

2. **Add the required patch key** – Every custom file must begin with the `patch:` top-level key to trigger Rime's patch mechanism.

3. **Define your overrides** – Insert your specific configuration changes using the syntax patterns described above.

4. **Deploy the changes** – Save the file and reload the input method using either the command line or hotkey:
   
   ```bash
   rime_deployer --reload
   ```

   
   On Windows, press **Ctrl+`** in the Rime status bar. On macOS, use **⌃+⌥+⌘+R**.

## Why Use Patches Instead of Editing Core Files?

Maintaining separate [`custom.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/custom.yaml) files provides three critical advantages:

- **Upgrade safety** – Updates to [`wanxiang.schema.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang.schema.yaml) or upstream defaults won't overwrite your personal settings because they reside in isolated files.
- **Granular control** – Enable or disable individual modules like `super_comment` or `super_replacer` without navigating large monolithic configuration files.
- **Portability** – Copy your entire `custom/` directory to another Rime installation to reproduce your exact configuration instantly.

## Summary

- **amzxyz/rime_wanxiang** uses a three-layer merge system: [`default.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/default.yaml) → [`wanxiang.schema.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang.schema.yaml) → `custom/*.custom.yaml`.
- Use `__patch` to append or modify existing tables like `speller/algebra` without replacing the entire list.
- Use direct key assignment to override scalar values like `menu/page_size` or replace entire module configurations.
- Always wrap custom configurations under the top-level `patch:` key in files located in the `custom/` directory.
- Reload Rime using `rime_deployer --reload` or system-specific hotkeys to apply changes.

## Frequently Asked Questions

### What is the difference between __patch and direct assignment in custom.yaml?

The `__patch` directive appends or modifies entries within an existing table defined in lower configuration layers, preserving the base schema's defaults. Direct assignment completely replaces the target key's value with your new definition. Use `__patch` when extending spelling algebra or adding replacer rules; use direct assignment when changing page sizes or replacing entire module configurations like `super_replacer`.

### Where should I place my custom.yaml file for Wanxiang?

Place your file in the `custom/` subdirectory of your Rime configuration folder, naming it [`wanxiang.custom.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang.custom.yaml) for the main schema or [`wanxiang_reverse.custom.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang_reverse.custom.yaml) for reverse lookup patches. The repository structure at `amzxyz/rime_wanxiang/wanxiang/custom/` provides the reference location for these user-level extensions.

### Do I need to restart my computer after editing custom.yaml?

No. Rime applies patches dynamically using the deployer. After saving your changes, run `rime_deployer --reload` from the command line, or use the reload hotkey (**Ctrl+`** on Windows, **⌃+⌥+⌘+R** on macOS). The schema will merge your new patches immediately without requiring a system restart.

### Can I use multiple custom.yaml files for different Wanxiang variants?

Yes. The patch mechanism supports multiple files targeting different schemas or variants. For example, you can maintain separate [`wanxiang.custom.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang.custom.yaml) for full-pinyin input and [`wanxiang_reverse.custom.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang_reverse.custom.yaml) for reverse lookup configurations. Each file operates independently, allowing granular control over different input modes while sharing the same underlying [`wanxiang.schema.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang.schema.yaml) base.