VimApi

Unofficial

Public API for interacting with the Vim emulation layer.

Obsidian ships the CodeMirror 5 Vim mode ported onto CodeMirror 6. The port is nightwing/cm6-vim-mode-experiment 103a9b5, taken from codemirror/CodeMirror@793c9e6, and its maintained successor is replit/codemirror-vim, whose 0ac05ab is what Obsidian’s build was traced to. The behavior these members describe is documented in the CodeMirror 5 vim API manual, but Obsidian’s copy has diverged from all of the above, so these types describe what Obsidian actually ships. Every type in this folder is sourced that way and does not repeat these links.

Two events are signalled on the editor: vim-mode-change, whose payload is a VimModeChangeEvent, and vim-command-done, which fires once a command completes or no command matched and carries no payload in Obsidian’s build. The vim-keypress event the manual documents is not signalled here.

Import:

import type { VimApi } from '@obsidian-typings/obsidian-catalyst-latest';

Signature:

export interface VimApi

Properties

	Property	Type	Description
	InsertModeKey	VimInsertModeKeyConstructor	Records a keystroke made while insert mode was active, so the insertion can be replayed.
	suppressErrorLogging	boolean	Whether errors thrown while handling a key are swallowed instead of being logged to the console.

Methods

Method	Returns	Description
_mapCommand(command)	void	Add a key mapping to the front of the key map, where it takes precedence over the mappings already there.
buildKeyMap()	void	Rebuild the key map from the current configuration.
defineAction(name, fn)	void	Register an action, which is a command that does its own work rather than waiting for a motion to give it a range. Actions may behave however they like, which makes them more flexible than motions and operators at the cost of orthogonality.
defineEx(name, prefix, func)	void	Register an Ex command, and map it to `:name`.
defineMotion(name, fn)	void	Register a motion, which moves the cursor without changing the document.
defineOperator(name, fn)	void	Register an operator, which transforms the range a motion selected.
defineOption(name, defaultValue, type, aliases?, callback?)	void	Register an option that `:set` can read and write.
defineOption(name, defaultValue, type, aliases?, callback?)	void	Register an option that `:set` can read and write.
defineOption(name, defaultValue, type?, aliases?, callback?)	void	Register an option that `:set` can read and write.
defineRegister(name, register)	void	Register a named register, so yanks and pastes can address it.
enterInsertMode(cm)	void	Enter insert mode.
enterVimMode(cm)	void	Turn Vim mode on for an editor, taking over its key handling and initializing its Vim state.
exitInsertMode(cm, keepCursor?)	void	Leave insert mode, returning to normal mode.
exitVisualMode(cm, moveHead?)	void	Leave visual mode, returning to normal mode.
findKey(cm, key, origin?)	(() => boolean \| undefined) \| undefined	Match a key against the key map, taking any keys already buffered into account.
getOption(name, cm?, cfg?)	Error \| VimOptionValue	Read a Vim option.
getRegisterController()	VimRegisterController	Get the controller owning every register.
getVimGlobalState_()	VimGlobalState	Get the Vim state shared by every editor.
handleEx(cm, input)	void	Run an Ex command.
handleKey(cm, key, origin?)	boolean \| undefined	Match a key and run whatever command it resolves to.
langmap(langmapString, remapCtrl?)	void	Set the langmap, which translates the keys of a non-Latin keyboard layout into the keys the mappings are written in.
leaveVimMode(cm)	void	Turn Vim mode off for an editor, giving key handling back to it and discarding its Vim state.
map(lhs, rhs, ctx?)	void	Map one key sequence to another, allowing the result to be remapped further. Implements Vim's `:map` — mapping `;` to `:`, which in Vim is `:map ; :`, is `map(';', ':')` here.
mapclear(ctx?)	void	Remove every user-defined mapping, leaving the built-in ones in place.
mapCommand(keys, type, name, args?, extra?)	void	Map a key sequence directly to a registered command, which is what `map` is built on.
maybeInitVimState_(cm)	VimStateVim	Get an editor's Vim state, creating it if Vim mode has not touched this editor yet.
multiSelectHandleKey(cm, key, origin?)	boolean \| undefined	Match a key and run it against every selection, for editors with more than one.
noremap(lhs, rhs, ctx?)	void	Map one key sequence to another without allowing the result to be remapped further.
resetVimGlobalState_()	void	Discard the Vim state shared by every editor and rebuild it, resetting every option to its default.
setOption(name, value, cm?, cfg?)	Error \| undefined	Write a Vim option.
unmap(lhs, ctx?)	true \| undefined	Remove a user-defined mapping.
vimKeyFromEvent(e, vim?)	string \| undefined	Translate a keyboard event into the Vim-style key name the mappings are written in.

Links to this page: