docs/manual/guide/03-keys.org

One key can run different commands depending on where the caret is. In the Emacs preset M-<right> demotes a heading, indents a list item and moves a table column right. Each binding can name a context, and Orgstar tries the bindings for a key from the highest priority down. The first one whose context holds and whose command can run at the caret wins.

When no binding for a key applies:

• In the Emacs and Mac presets, a single key goes to the text system and does what it normally does. TAB outside a heading, drawer edge or table types a tab; S-<right> on plain text extends the selection.
• A key sequence of two or more keys runs its highest-priority command anyway, so you see that command's message (for example "Not on a heading").
• In the Doom preset the keys go on to the Vim engine (see Vim editing).

In a file that is not an Org file, org. commands never apply, so their keys fall through as above.

A prefix is a key that starts longer sequences, such as C-c, C-c C-x, C-x n or, in the Doom preset, SPC and SPC m. After a prefix, Orgstar waits for the next key and shows the keys typed so far in the echo area, followed by a dash: C-c C-x-.

If you pause on a prefix for 0.6 seconds, a panel of key hints opens above the echo area. It lists each key that can follow, sorted by key, with the title of the command it runs, or +prefix when it leads to a longer sequence. This is Orgstar's version of which-key. The hints follow the current keymap, including your keymap.toml, and in the Doom preset the current evil state. When a key has several contexts (C-c C-c is the common case), the hint shows the command that would run at the caret; where none of them applies, it shows the highest-priority one.

C-g during a prefix cancels it; in the Emacs and Mac presets the echo area shows Quit. A sequence that nothing binds shows, for example, C-c z is undefined and does nothing. In the Doom preset this holds for sequences that start with SPC or with a Control or Meta key; see How keys are handled for the others.

A key bound by itself cannot also be a prefix. When a keymap binds both C-c and C-c C-t, C-c always waits for the next key, so the binding for C-c alone never runs.

The file is a list of [[bind]] tables, one per binding:

# C-c t cycles the TODO keyword.
[[bind]]
keys = "C-c t"
command = "org.todo.cycle"

The key reference gives each command's id after its title. Commands no preset binds are listed under Unbound commands. A binding whose command id Orgstar does not know is skipped and reported when the file loads (see Reloading and errors).

Orgstar reads a subset of TOML: [[bind]] headers, key = value lines, basic "..." and literal '...' strings, true and false, integers, and # comments. Arrays, inline tables and multi-line strings are not supported.

Modifiers combine: C-M-s-<left> is ⌃⌥⌘←. <tab>, <return>, <escape> and <backspace> are accepted as other names for TAB, RET, ESC and DEL, and <backtab> for S-TAB.

Shift with a letter is written as the capital letter: S-a and A are the same key, and so are C-S-h and C-H. With other keys Shift stays a modifier: S-TAB, S-<up>, M-S-RET.

A backslash in a basic string must be doubled. These two lines are the same key, ⌃⌘\:

keys = "C-s-\\"
keys = 'C-s-\'

Bindings are read in order: the preset first, then your file from top to bottom. When several bindings have the same keys, later ones are tried first. A binding in your file without when therefore takes its keys everywhere, hiding every context-specific preset binding for them. A binding with when is tried first only in its context; elsewhere the preset's bindings still apply.

# M-RET in a table inserts a row; on headings and items it does what the preset says.
[[bind]]
keys = "M-RET"
command = "org.table.insert-row"
when = "table"

Set command to "none" to remove a key. A "none" binding without when hides every earlier binding of exactly those keys, so the key goes to the text system (or, in the Doom preset, to Vim):

# Leave C-t to macOS's transpose and C-k to its kill.
[[bind]]
keys = "C-t"
command = "none"
[[bind]]
keys = "C-k"
command = "none"

Limitations:

• A "none" binding with when has no effect. You cannot unbind a key in one context only; bind it to another command in that context instead.
• Unbinding a prefix does not remove the longer sequences under it. Unbinding C-c C-x leaves C-c C-x C-i and the rest working. Unbind each sequence you want gone.

In the Doom preset every binding belongs to a state. A binding without mode never runs in the Doom preset, and a binding with mode never runs in the Emacs or Mac preset. mode = "visual" covers visual, visual-line and visual-block. To bind a key in more than one state, write one table per state:

# SPC n a opens the agenda.
[[bind]]
keys = "SPC n a"
command = "app.agenda"
mode = "normal"

# C-c n inserts a heading in normal and insert state.
[[bind]]
keys = "C-c n"
command = "org.heading.insert"
mode = "normal"
[[bind]]
keys = "C-c n"
command = "org.heading.insert"
mode = "insert"

A mode other than normal, insert or visual (including visual-line) is reported when the file loads, and the binding is skipped.

Orgstar watches the configuration folder and reloads keymap.toml when you save it. It also reloads when you change the preset, and when you run Reload Keymap (app.reload-keymap, in the palette, and SPC h r r in Doom normal state), which shows Keymap reloaded.

Problems are reported in the echo area with the line number, for example keymap.toml: line 12: unknown context tabel (and 1 more). A binding with bad or missing keys, a missing command, a command id Orgstar does not know, an unknown when or mode, or a table other than [[bind]] is skipped; the rest of the file still applies. A file that is not valid TOML is ignored as a whole and the error is shown; the preset alone applies until you fix it.

Settings ▸ General ▸ Import from Emacs… reads your Emacs or Doom configuration and offers, among other things, the key bindings it finds: global-set-key, keymap-global-set, define-key, keymap-set, evil-define-key and Doom's map! with :leader, :localleader, state keywords and :prefix. Bindings to commands Orgstar has are appended to keymap.toml under a # Imported from Emacs. comment, leaving out bindings the file already has. Keys written as vectors, such as [f5], are skipped. See Alongside Emacs.

Each key goes first to the keymap for the current state, then to the Vim engine:

1. Keys with ⌘ go to the menus.
2. If a Vim command is half typed (after d, "a, 3 and so on), the key goes to Vim.
3. Otherwise the keymap gets the key. A prefix such as SPC, g, z, [, ], C-c or C-x waits for the next key, with key hints as described above. A complete sequence runs its command if the binding's context holds and the command can run at the caret.
4. Anything the keymap does not take goes to Vim, as typed. In insert state, keys Vim does not handle are typed as text.

Two consequences:

• Keymap commands do not take counts or registers. Once you type a count or a register, the following keys go straight to Vim.
• A sequence the keymap does not complete after SPC, C-c, C-x or another Control or Meta prefix is undefined: the echo area shows, for example, SPC j is undefined, and nothing runs. After g, z, [ or ], which are Vim prefixes too, the keys are replayed into Vim, so gu and gq reach the Vim engine although the keymap binds other g keys.

Leaving insert state moves the caret back one character, as in Vim. A mouse click leaves visual state. In the keymap, "visual" is the state name for all three visual states.

In insert state, C-w deletes the word before the caret and C-u deletes back to the line's indentation (or to the start of the line when the caret is already there). The rest of insert state is the Emacs preset's Org keys, the Doom insert-state keys in the reference (TAB and S-TAB on headings, items and tables, C-t and C-d, C-S-h/j/k/l, C-SPC for completion) and ordinary typing.

Motions move the caret in normal state, extend the selection in visual states, and give the range for an operator. A count before a motion repeats it.

Search patterns are ICU regular expressions as macOS uses them, close to PCRE; Emacs and Vim regexp syntax such as \(...\) or \< does not work. :noh is accepted and does nothing; searches are not highlighted.

M-q runs Fill Paragraph in normal, insert and visual state. In visual and visual-line state it fills every paragraph the selection touches and leaves the caret where it was. In visual-block state it fills the paragraph at the caret, as evil does with transient-mark-mode off. In each, if the text changed, the editor returns to normal state, otherwise the selection stays.

Counts multiply: 2d3w deletes six words. Doubling an operator with a count acts on that many lines: 3dd.

Single-key changes:

o and O open a line below or above with Org's indentation: under a list item, aligned with the item's text; under a heading, none; otherwise the line's own indentation.

After an operator, or in visual state to select, i takes the inner object and a the object with its surrounding space or delimiters.

Tag objects (it, at) and sentence objects (is, as) are not available.

A count is digits before a command; 0 only counts after another digit. A register is " and a name before the count and command: "ayy, "a3dd, "ap.

Pasting from the clipboard is linewise when its text is what the last linewise yank or delete put there; text copied in another app pastes as characters. Numbered registers "1 to "9, and the read-only registers such as "%, are not available.

Registers and macros are shared by every buffer, as in evil: a yank into "a in one file pastes with "ap in another. Lowercase marks and the jump list belong to the buffer and are gone when it closes. Nothing is kept when Orgstar quits.

. repeats the last change made in normal state, including text typed in insert state that the change began: ciwfoo ESC then . changes the next word to foo. A count before . replaces the original count.

Changes made from visual or visual-block state, visual S surrounds, and keymap commands (such as M-l or SPC m t) are not repeated by ..

A macro replays the keys you typed, including keymap commands, leader keys and insert-state typing. Keys with ⌘ are not recorded. Macros are kept apart from text registers: "ap does not paste a macro, and "ay does not change one. Macros can call macros up to 20 deep.

m a sets mark a (any letter) at the caret. Marks move with the text as you edit. ' a goes to the first non-blank of the mark's line, ` a to its exact position. '' and `` go back to where the last jump started.

Jumps are G, gg, %, {, }, n, N, *, #, ', `, H, M, L, the snipes s, S, f, F, t and T, and searches with / and ?. Each jump adds its starting point to the jump list, which keeps the last 100. C-o goes back through the list and C-i forward again. A new jump after C-o drops the places you went back past.

Lowercase marks belong to the buffer, and so do C-o and C-i. Uppercase marks (mA to mZ) are file marks, shared by every buffer: 'A or `A in another buffer shows the buffer the mark was set in, at the mark. A file mark goes away when its buffer closes.

v selects characters, V whole lines, C-v a rectangular block. Motions and text objects extend the selection; o moves the caret to the other end. gv in normal state selects the last visual selection again.

In visual and visual-line state:

The Emacs preset's Org keys (C-c ..., M-h/j/k/l, M-<left> and so on) also work in visual state.

In visual-block state:

Block I, A and c copy the typed text to the other lines only when it contains no newline. A yanked block pastes as ordinary lines, not as a block.

As evil-surround:

For ds and cs, brackets are found across lines; any other character is matched on the caret's line. Tags (t) and functions (f) are not supported.

gc with a motion or text object, gcc for lines, and gc in visual state toggle Org comments. Lines get # followed by a space at the shallowest indentation among them; blank lines are left alone. When every non-blank line is already a comment, the comments are removed instead. This is comment-or-uncomment-region in Org, as evilnc-comment-operator runs it.

Besides the leader, the preset binds these evil-org and Doom keys in normal state. TAB, S-TAB and RET in normal state, and the Emacs preset's Org keys in every state, are listed in the key reference. gj and gk move by Org element; see Motions.

SPC in normal state is Doom's leader and SPC m its local leader for Org. Pause after SPC to see the key hints.

: opens a prompt in the echo area. Orgstar understands these:

Anything else shows Not an editor command. Ranges other than %, the c flag, :g, :normal and :set are not available, and : does not work in visual state.

Things evil users may reach for that Orgstar does not have: zz, zt and the other scroll and fold z commands except za, zc, zo and zA; C-a and C-x to increment numbers; gi, g;, gJ; replace state (R); &; q:; the numbered and read-only registers; tag and sentence text objects.

No preset binds these. Run them from the palette or a menu, or bind them in keymap.toml.

At the very start of a heading line, with org-use-speed-commands on. The same in every preset (Doom: insert state).