How to read this manual
Four parts, fourteen chapters. You are not meant to read it end to end.
The manual is in four parts: Part 1 is concepts and setup (what Erya is, how to install it, how to read the screen), Part 2 is everyday editing (opening, typing, searching, undo), Part 3 is advanced features (encodings, large files, hex, comparison), and Part 4 is settings and reference (shortcuts, languages, lookup tables).
Numbering is part-chapter: 3.4 is the fourth chapter of Part 3, and sections add a third number, like this one — 1.1.1. When the text says “see 4.1”, that is the first chapter of Part 4, reachable from the sidebar on the left.
Three ways through it
- New to Erya: read 1.1 to 1.3, then 2.1 (opening and saving). Those four chapters are enough to do real work.
- Coming from another editor: read 1.3 (the screen) and 4.4 (the shortcut tables), then dip in as needed. If you use nano or vim, start with 4.1 — switching to a familiar key profile is faster than relearning.
- Just need to open one file right now: 1.2.5 covers starting, 1.3 covers the screen, and Ctrl+X exits. Three minutes.
The box at the top left (or ⌘K / Ctrl+K) does two things: it highlights matches in this chapter in yellow so you can step through them with Enter, and it lists other chapters that cover the same subject. The text inside the screen mock-ups is searchable too.
Keys appear as Ctrl+S; file paths and commands appear as ~/.config/erya/keymap.toml. Do bear in mind that Erya's shortcuts can be swapped wholesale (see 4.1). This manual always uses the built-in Erya Terminal Safe profile; if you have changed profiles, trust the hint bar on the second row and the F1 help instead — those always show the keys you actually have.
Everything here is written from the current source code. Planned features are not covered, and neither is what “ought” to happen. When the manual says an action has no default key, or that something is unsupported in a particular mode, that is the present state of the program.
What Erya does and does not do
In one line: a text editor that runs in a terminal and takes CJK documents seriously.
The name comes from a classical gloss — er, to be near; ya, to be correct — and the program is a Rust rebirth of the Han Shu (漢書) Chinese word-processing system from DOS days. It was rewritten from scratch, specification first, and contains none of the original source code or assets; it has no affiliation with the original development team.
It runs inside a terminal (Terminal.app, iTerm2, Windows Terminal, an SSH session — all fine), fills the window while it runs, and restores the window when it exits. This is what it looks like:
| Erya does this | Erya does not do this |
|---|---|
| Open, edit, and save plain text files | Layout, fonts, bold and italic (it is not a word processor) |
| Detect and convert UTF-8 / UTF-8 BOM / Big5 / GBK / Shift_JIS | UTF-16 and UTF-32 (reported as unsupported on open) |
| Multiple tabs, search and replace, undo and redo | Split views, two places in one file at once |
| Syntax highlighting chosen from the filename | Linting, completion, go-to-definition (it is not an IDE) |
| Formatting for TOML, YAML, and JSON | Formatting anything else (it never calls external tools) |
| A hexadecimal view, and byte editing for binary files | Disassembly or structure parsing (it is not a hex workbench) |
| Side-by-side comparison with two-way copying | Three-way merges, version control (there are no Git features) |
| Read-only reading and log following for files past 64 MiB | Editing anything in large-file mode |
| Phrases and keyboard macros | Plug-ins, a scripting language, a package manager |
Erya has no autosave and no crash recovery. Anything you have not saved with Ctrl+S lives only in memory. It does stop and ask when you close a tab or exit (see 2.1.8), but if the terminal is closed, the SSH connection drops, or the machine crashes, unsaved text is gone.
How it differs from vim and nano
Shortest answer: no modes to memorise, and CJK text is a first-class citizen.
Terminal editors are not in short supply. Erya exists for a specific set of problems: CJK documents that do not line up in a terminal, encodings that get mangled in conversion, and older files that are still Big5. That shapes a few of its decisions.
| Erya | vim | nano | |
|---|---|---|---|
| Modes to learn | None. Open it and type | Yes: command and insert | None |
| Discovering keys | Row 2 always lists the common ones; F1 has the full list | You learn them first | Two rows at the bottom |
| CJK encodings | Detected, always shown, converted with F7 | Set fileencoding by hand | Not handled |
| Full-width alignment | Measured in terminal columns; full width counts as two | Mostly fine | Mostly fine |
| Emoji and combining marks | Moves and deletes by grapheme cluster | Depends on the build | Often splits them |
| Block selection | Built in; can fill and shift as a unit | Yes (Ctrl+V block mode) | No |
| File comparison | Built in, F4 | Launch vimdiff | No |
| Hexadecimal | Built in, Ctrl+P | Pipe through xxd | No |
| Rebinding keys | One TOML file, twelve profiles included | vimrc (powerful, but a project) | nanorc (limited) |
The keymap/ directory ships nano, vim, and emacs profiles, plus VS Code, Visual Studio, IntelliJ, Eclipse, and macOS variants. Press F2, pick one, press Enter — no config file needed (see 4.1.3).
The whole system in five blocks
Every screen in Erya belongs to one of these five.
One thing to note: none of these five have menus. Erya has no menu bar at all; every feature is reached by a key. When you cannot find something, press F1 — that list is the feature index (see 1.3.8).
The life of a document
From open to written back, it passes five stations.
- Open. Name the file on the command line, or press Ctrl+O for the file dialog. If the path is already open in a tab, Erya switches to it rather than opening a second copy (2.1.1).
- Classify. Erya looks at the size and the first 8 KiB — is there a NUL byte? — decides which mode to use, and guesses the encoding at the same time (3.1.1).
- Edit. Ordinary text files spend most of their life here. Each tab keeps its own cursor, search terms, and up to 100 undo steps (2.4.1).
- Convert (optional). To turn an old Big5 file into UTF-8, or CRLF into LF, press F7 / F8 before saving. The conversion happens on the next save, not immediately (3.1.2).
- Save. Ctrl+S writes a temporary file in the same directory, swaps it into place atomically, and on Unix restores the original permissions (2.1.6).
Three kinds of reader, three routes
Work out which one you are, then read only those chapters.
Writing prose
Drafting, note-taking, tidying up older documents
- Opening, tabs, saving
- Search, replace, undo
- Encoding and line-ending conversion
- Paragraph reflow, phrases
Route: 1.2 → 1.3 → 2.1–2.4 → 3.1
Editing configs on a server
SSH in, change a conf, read a log, diff two files
- Options and environment variables
- Highlighting and TOML/YAML/JSON formatting
- Large files and log following
- Comparing two configurations
Route: 1.2 → 1.3 → 2.1 → 3.1 → 3.2 → 3.4
Making it fit your hands
Changing shortcuts, the language, or standardising a team setup
- Twelve bundled key profiles
- The keymap editor and Save As
- Where a config file is picked up
- Interface language and custom translations
Route: 1.3 → 4.1 → 4.2 → 4.4
Being all three at once is normal. In that case work through Parts 1 and 2 in order, and come back to Parts 3 and 4 when you need them.
Six things to remember first
You will meet them all again; this is just where they start.
- There is no autosave. Erya never saves behind your back and has no crash recovery. Ctrl+S is the only thing that writes to disk (2.1.5).
- Exit is Ctrl+X, not Ctrl+C. In the default profile Ctrl+C copies; it does not interrupt. F11 closes a tab (2.1.3).
- Shortcuts can be swapped wholesale, so the manual may not match your keys. Row 2 and F1 always show what you actually have (4.1).
- Encoding and line endings take effect on the next save. F7 and F8 change the status bar; the file changes when you save (3.1.2).
- Three modes cannot edit anything. Large-file read-only, the hexadecimal view of a text file, and streamed binary files. The status bar names the one you are in (3.2, 3.3).
- Block selection and line wrap are mutually exclusive. Their coordinate systems disagree, so enabling one while the other is on is refused with a message (2.2.5).
Where each term is explained
Terms used in this chapter. The full glossary is 4.4.8.
| Term | In one sentence | See |
|---|---|---|
| Tab | One of several files open at once, each with its own cursor and undo history. | 2.1.3 |
| Hint bar | Row 2; always lists the keys that work on the current screen. | 1.3.3 |
| Status bar | Second from the bottom: filename, line and column, mode, encoding, line endings. | 1.3.5 |
| Message row | The last row; results and confirmation questions appear here. | 1.3.6 |
| Key profile | A TOML file mapping actions to keys; swappable as a set. | 4.1 |
| Grapheme cluster | What looks like one character on screen, however many code points it takes. | 2.2.3 |
| Block selection | A rectangular selection you can fill with a character or shift as a unit. | 2.2.5 |
| Large-file mode | The read-only reading mode used from 64 MiB upwards. | 3.2 |
| Hexadecimal view | The document laid out as bytes; read-only for text files. | 3.3 |
| Binary file | A file with NUL bytes or undecodable content; opens straight into byte view. | 3.3.5 |
| Temporary copy | The working file used during a comparison; originals stay untouched until you apply. | 3.4.1 |
| Phrase | A captured string you insert repeatedly, stored as JSON. | 2.4.3 |
| Macro | A recorded key sequence you replay, stored as JSON. | 2.4.6 |
| Atomic save | Write a temporary file, then swap it in — no half-written files, ever. | 2.1.6 |