Introduction

Vim Motions provides comprehensive support for Markdown tables, including structural navigation, cell-level text objects, manipulation commands, and native table editor integration for Live Preview that preserves Vim’s editing power.

Cell navigation

Table navigation

Navigate Markdown table cells without leaving Vim mode.

KeybindingDescription
]\| or ]cMove to the next table cell
[\| or [cMove to the previous table cell
]rMove to same column in next row
[rMove to same column in previous row
<Tab>In insert mode in a revealed table: next cell, adding a row from the last one
<S-Tab>In insert mode in a revealed table: previous cell
<CR>In insert mode in a revealed table, inside a cell: same column, next row, adding a row from the last one
<S-CR>In insert mode in a revealed table, inside a cell: insert a <br> line break
Link to original

Table navigation commands allow you to move between cells horizontally and vertically.

  • Wrapping: Horizontal navigation (]|, [|, ]c, [c) wraps around to the next or previous row when reaching the end or beginning of a row.
  • Separator-skip: Vertical navigation (]r, [r) automatically skips over table separator rows (the |---| lines) to land on the same column in the next or previous content row.

Warning

On many non-US keyboard layouts, the pipe character (|) requires a modifier key (like AltGr) that may conflict with Vim’s key capture. If ]| or [| do not work on your keyboard, use the alternative ]c and [c bindings.

Table text objects

Table text objects

Operate on table cells with standard Vim operators.

KeybindingDescription
i\|Inside table cell (content between pipes)
a\|Around table cell (content plus trailing pipe)
Link to original

Table text objects allow you to operate on the content of individual cells using standard Vim operators:

  • di|: Delete the content of the current cell.
  • ci|: Change the content of the current cell (delete and enter insert mode).
  • yi|: Yank (copy) the content of the current cell.
  • vi|: Visually select the content of the current cell.

The a| variant includes the surrounding pipes and padding.

Tip

Escaped pipes (\|) inside table cells are treated as cell content, not boundaries. For example, | foo \| bar | baz | is a two-column table where the first cell contains foo \| bar. \\| (escaped backslash followed by pipe) is treated as a real boundary.

Table manipulation

Table manipulation

Manage table structure using the <leader>t prefix.

KeybindingDescription
<leader>tmInsert table
<leader>toAdd row below
<leader>tOAdd row above
<leader>tJMove row down
<leader>tKMove row up
<leader>tddDelete row
<leader>tiLAdd column to the right
<leader>tiHAdd column to the left
<leader>tLMove column right
<leader>tHMove column left
<leader>tdcDelete column
<leader>talAlign column left
<leader>tacAlign column centre
<leader>tarAlign column right
<leader>trRealign table columns
Link to original

A suite of manipulation commands is available under the <Leader>t prefix for structural changes to the table:

  • <Leader>to: Add a row below the current row.
  • <Leader>tO: Add a row above the current row.
  • <Leader>tJ: Move the current row down.
  • <Leader>tK: Move the current row up.
  • <Leader>tdd: Delete the current row.
  • <Leader>tiL: Add a column to the right.
  • <Leader>tiH: Add a column to the left.
  • <Leader>tL: Move the current column to the right.
  • <Leader>tH: Move the current column to the left.
  • <Leader>tdc: Delete the current column.
  • <Leader>tal, <Leader>tac, <Leader>tar: Align the current column left, centre or right.
  • <Leader>tr: Realign the entire table.

Note

These manipulation commands call Obsidian’s internal table commands. In native mode, they work when the cursor is inside the table. In reveal mode they work on the revealed table through text-based equivalents, since it has no widget for Obsidian’s commands to drive. In raw mode, use Source mode or manual Markdown editing.

Table auto-formatting

Vim Motions includes built-in auto-formatting for tables:

  • Manual realignment: Use <Leader>tr or :tablerealign to realign a table’s columns at any time. In table-nav mode, = does the same.
  • The same output as Obsidian: :tablerealign writes exactly what Obsidian’s table editor writes for the same table — each column as wide as its longest cell plus one space either side, content placed by the separator’s colons (right-aligned against the right edge, centred with the odd space after it), and width counted the way Obsidian counts it, in UTF-16 code units. A table therefore does not change when you switch between native and reveal. The cost is that a row containing CJK characters or emoji does not line up in reveal’s monospace grid, exactly as it does not in Source mode.
  • By default, Vim Motions never reformats a table on its own — not while you type, not when the cursor leaves the table. Realignment happens only when you ask for it, so the cursor stays where you expect it. In reveal mode, tableautorealign can do it for you.
  • Obsidian does realign automatically, in native mode: its table editor realigns the columns when it commits a cell edit. In reveal mode, which never uses Obsidian’s cell editor, the same happens only if you set tableautorealign to insertleave, or to typing to realign as you type — see tables > Reveal mode.

Table widget in Live Preview

Vim Motions integrates with Obsidian’s native table editor in Live Preview. These modes are available via set tablewidget:

  • auto (default, Automatic): reveal while the Neovim backend is connected, and native otherwise. It switches when the backend connects or disconnects. Obsidian’s table editor gives each cell an editor of its own, and the backend mirrors only the note’s editor, so with the backend Neovim never sees a cell being edited. A revealed table is lines of the note, which Neovim edits directly.
  • native (Always native): Obsidian’s native table widget renders in Live Preview. Cell editors are native Obsidian editors with vim injected via registerEditorExtension(). The native editor handles wikilinks, pipe escaping (| → \|), cursor positioning, and <br> conversion automatically.
  • reveal (experimental, Always reveal): Obsidian renders every table the cursor is not in, and the table holding the cursor becomes ordinary editor lines that Vim edits directly. See tables > Reveal mode below.
  • raw (deprecated, will be removed): despite the name it does not show Markdown source. It hides Obsidian’s widget with CSS while Obsidian still replaces the table’s range, so the table renders as nothing at all. Use Source mode to edit a table’s source. No widget rendering. Useful for users who prefer source-style editing in Live Preview. The vim cursor remains fully visible in raw mode — cursor suppression only activates when a native table widget is visible.

In source mode, tables are always rendered as raw markdown regardless of the tablewidget setting. The cursor behaves normally — no cursor suppression occurs.

The tablenav setting (on by default) controls whether the table-nav overlay activates on top of the native editor. With tablenav off, the native table editor still provides full vim cell editing with cross-cell h/j/k/l navigation — just without the overlay UI.

ConfigurationExperience
native + tablenav (default without the Neovim backend)Full table-nav overlay with cell highlighting and structural commands
native + notablenavNative table editor with vim cell editing and cross-cell navigation
rawRaw markdown tables
revealObsidian’s table when idle; the active table as editable source

Reveal mode

Warning

Experimental. It is what auto, the default, uses while the Neovim backend is connected. To use it with the plugin’s own Vim too, choose set tablewidget=reveal, vim.opt.tablewidget = "reveal" or Always reveal under Settings → Vim Motions → General → Table widget in live preview.

With reveal, tables you are not editing keep Obsidian’s own table — formatted cells, images and links, the row and column buttons, drag to reorder, sort and the context menus. When the cursor enters a table, that table turns into its Markdown source, shown as an aligned grid, and leaves the grid again when the cursor moves out. It is the way Live Preview already treats a heading or a link, applied to tables.

The source lines belong to the note’s own editor. There is no second editor inside the table and nothing to keep in sync, so everything Vim does elsewhere works the same way inside a table.

What works

Each item below is covered by a test in test/specs/table-reveal*.e2e.ts or test/specs/rpc-table-reveal.e2e.ts.

  • Normal-mode editing with the note’s one undo history: x, dd, u, counts, and . repeating an insert on the next row
  • Charwise, linewise and visual block selections, including a V selection that starts above the table and extends into it
  • Insert mode, including typing a new table from scratch without the cursor being pulled into the header (issue #121)
  • Macros recorded and replayed down the table’s rows
  • Entering with j/k or a / search: the table opens on the same keystroke and the cursor never jumps to a cell, including on the separator row
  • In-file search: closing it on a match inside the table keeps the table open
  • Clicking a cell of an idle table places the cursor in that cell, on the clicked character for plain text
  • The :table* commands and their <leader>t bindings, while other tables in the note keep Obsidian’s widget
  • Switching between Live Preview and Source mode with the cursor in a table
  • IME composition, inside a cell and at the end of a row, committed once and reversed with one u
  • Snippets: a prefix expands in a cell and Tab walks its tabstops
  • Flash and EasyMotion label targets inside the table and jump to them
  • Hint mode labels a link in the table the way it labels any link shown as source, and opens it
  • The animated cursor is painted on the caret inside the table
  • In insert mode, Tab and Shift-Tab move to the next and previous cell, wrapping across rows and skipping the separator, and Tab in the last cell adds an empty row
  • In insert mode, inside a cell, Enter moves to the same column in the next row, adding a row from the last one, and Shift-Enter inserts a <br> line break; at the end of a row both start a new line, so a table can still be typed row by row
  • With tableautorealign=insertleave, leaving insert mode realigns the table you edited, keeping the cursor on its character; with tableautorealign=typing the columns follow your text as you type. One u undoes an edit and its realign together, and . repeats only what you typed
  • A | typed inside [[…]] is written as \|, and || typed under a header with no separator yet becomes the separator
  • The status bar shows the cursor’s column and its header, and every cell of that column is highlighted (tablecolumnhighlight, on by default)
  • The cell motions ]|, [|, ]r, [r and the text objects i|, a|
  • The column alignment commands, <Leader>tal, <Leader>tac and <Leader>tar
  • Obsidian’s own Vim key bindings, instead of the bundled engine: the same entering, editing, visual block and click behaviour
  • The Neovim backend: the cursor follows Neovim into the table, edits land on Neovim’s row, and Neovim’s extmarks render inside the table

How it looks

The active table is shown in a monospace font with ligatures off, so a realigned table’s columns line up. Every bit of inline Markdown inside it — **bold**, [[links]], inline math — is shown as source, not rendered, which is what keeps the columns aligned. The delimiters and the separator row are dimmed, the header row is tinted, and the cell holding the cursor is highlighted, with a fainter highlight on the rest of its column. The tint, the dimming and the cell highlight use your theme’s table variables; the column highlight uses its hover colour.

Run :tablerealign (or <Leader>tr) to pad the columns, or set tableautorealign to have that happen when you leave insert mode (insertleave) or as you type (typing).

Moving between cells, line breaks and realigning

In insert mode, Tab moves to the start of the next cell’s content and Shift-Tab to the previous one. Both wrap across rows and skip the separator row. Tab in the last cell of the table adds an empty row, with its pipes where the row above has them, and puts the cursor in its first cell. Shift-Tab in the very first cell does nothing.

Enter moves to the same column in the next row, skipping the separator, and on the last row adds an empty row with the cursor in the same column. Shift-Enter inserts <br>, which is how Obsidian’s cell editor writes a line break typed in a cell; a plain newline would split the row. Both match Obsidian’s own table editor, measured at 1.13.7. Outside a table, Enter does what it did before. At the end of a row, with nothing after the cursor, Enter and Shift-Enter start a new line as in plain text instead, so a table can still be typed row by row — once its separator is typed the table is revealed, and the Enter that ends the separator must not drop the cursor into a new row’s first cell. mkdnflow.nvim makes its own Enter navigation opt-in for the same reason.

Obsidian’s own table editor moves the same way, but it selects the content of the cell it moves to. Here the cursor lands at the start of that content instead, as it does in mkdnflow.nvim, table-nvim and org-mode, because a selection is not an insert-mode state in Vim. Outside a table, and in normal mode, Tab does what it did before. A snippet that can expand or walk its tabstops keeps Tab, and so does an insert-mode mapping of your own.

tableautorealign (Settings → Vim Motions → General → Realign revealed tables on edits, set tableautorealign=… or vim.opt.tableautorealign = "…") has three values:

  • off (default): only :tablerealign realigns.
  • insertleave: leaving insert mode realigns each table you edited during that insert. set tableautorealign, with no value, means this, as it did when the option was a toggle.
  • typing: every edit you type realigns the table straight away, so the columns widen and narrow with your text, and leaving insert mode realigns once more. A realign changes only the padding that differs, so it costs well under a millisecond even for a 1,000-row table. During an IME composition it waits for the commit.

Either way the output is the same as :tablerealign. The cursor stays on the character it was on, in the same cell, and one u undoes an edit and its realign together. . and macros repeat only what you typed, not the padding a realign added: Neovim leaves text an insert-mode <Cmd> mapping sets out of . in the same way. <C-o> does not count as leaving insert mode. A table is left alone if any of its rows does not both start and end with a pipe, so a row you are still typing is never rebuilt under you, and a quoted table keeps its > markers.

The cell keys follow the same rule. A row that Tab or Enter adds is not repeated by ., and moving to another cell does not split what . repeats: iab, Tab, cd, then . inserts abcd, as Neovim does across a <Cmd> mapping. The <br> of Shift-Enter is typed at the cursor, so . repeats it.

None of these keys, nor tableautorealign, applies under the Neovim backend, where Neovim owns every key and every mode change, so Tab and Enter are Neovim’s.

Typing pipes, headers and alignment

A | typed inside an unclosed [[ on a revealed row is written as \|, so a wikilink alias or an embed size, such as [[page|alias]] or ![[image.png|200]], stays inside its cell. Obsidian’s own table editor escapes every pipe typed in a cell. A revealed table cannot, because there a typed | is how you make a new column, so only the pipes inside a wikilink are escaped. A pipe you escaped yourself is left alone.

To start a table, type its header row, then || as the whole of the next line: it becomes the separator row, one column per header cell, sized to the header’s cells. This works only below a header that has no separator yet, so || typed as a row of an existing table stays a row.

<Leader>tal, <Leader>tac and <Leader>tar (:tablealignleft, :tablealigncenter, :tablealignright) set the current column’s alignment by rewriting its separator cell, then realign the table so the content moves to match. In native mode they run Obsidian’s own alignment commands. Under the Neovim backend, typed text goes to Neovim, so the pipe escape and the || separator do not apply there.

Which column you are in

While the cursor is in a revealed table, the status bar shows its column, the number of columns and the column’s header, for example Col 2/3 · Value. When the cursor’s row has a different number of cells from the header, it adds a warning, for example row has 4 cells, so a stray or missing pipe shows up while you type. Every cell of the cursor’s column is highlighted, more faintly than the cursor’s own cell. To highlight only the cursor’s cell, turn off Settings → Vim Motions → General → Highlight table cursor column, or use set notablecolumnhighlight or vim.opt.tablecolumnhighlight = false.

What is different from the other modes

  • The table changes size when the cursor enters or leaves it, since a formatted table and its source are not the same shape.
  • Long rows wrap. A revealed row is an editor line, and an editor line cannot scroll sideways on its own; a table wider than the note wraps until the cursor leaves it.
  • Mouse selection across the cells of an idle table is not available, because a click places the cursor instead. Select with <C-v> once the table is revealed.
  • Obsidian does not realign a table after an edit, because its cell editor is never used. Use :tablerealign, or set tableautorealign.
  • A snippet whose body contains a | or a newline damages the row, exactly as typing one would. Obsidian’s cell editor escapes these; a revealed table is plain source. Escape the pipe in the snippet definition.

When it falls back

reveal is skipped, with a one-time notice, on mobile, which has not been measured yet. It also falls back to Obsidian’s table editor, with a notice, if the version of Obsidian in use does not expose what the mode relies on; see known-limitations > Tables.

Table-nav mode

When the cursor enters a table in Live Preview with tablenav enabled, a navigation overlay activates. This mode allows you to navigate between cells and perform structural changes without entering the cell editor.

Keybindings

KeyAction
h / j / k / lNavigate between cells
Tab / Shift+TabNavigate to next / previous cell (wraps across rows)
{count}j, {count}l, etc.Navigate with count prefix (e.g., 3j)
i / a / c / s / EnterStart editing the active cell
EscapeExit table-nav and return to the main editor
oAdd a row below
OAdd a row above
ddDelete the current row
dcDelete the current column
JMove the current row down
KMove the current row up
HMove the current column to the left
LMove the current column to the right
IAdd a column to the left
AAdd a column to the right
=Realign the table
.Repeat the last structural command

Other keys do nothing in table-nav, including u, zz and :. Start editing the cell, or leave the table, to use them. Text you type straight after i, a, c, s or Enter goes into the cell, however quickly it follows.

Fork-only feature

Table-nav mode requires the bundled vim engine or the Neovim backend. If you are using Obsidian’s built-in vim mode, the plugin falls back to standard cell editing. Under the Neovim backend the overlay works normally: Obsidian’s keymap scope consumes its keys before they reach Neovim.

Tip

The native mode provides the best vim editing experience for tables. Obsidian’s native table widget handles rendering while vim is injected into cell editors. Structural commands let you add, delete, and move rows and columns without leaving the table. Notes with multiple tables are fully supported — each table is independently navigable.

Viewport scrolling

When navigating through a table taller or wider than the viewport, the editor scrolls both vertically and horizontally to keep the highlighted cell visible. This works even with tables that extend well beyond the screen.

Native mode vim navigation

In native mode, motions in normal mode cross cell boundaries automatically:

KeyIn cellAt boundary
lMove right within cellMove to next cell (same row)
hMove left within cellMove to previous cell (same row)
jMove down within cellMove to same column in next data row (skip separator)
kMove up within cellMove to same column in previous data row (skip separator)
w / WMove to next word within cellMove to next cell
b / BMove to previous wordMove to previous cell
e / EMove to end of wordMove to next cell
ge / gEMove to end of previous wordMove to previous cell
j at last row—Exit table downward
k at header—Exit table upward

Count prefixes work for cross-cell j/k motions: 3j crosses 3 rows.

Operator-pending (dj, yl) and visual mode motions are confined to the current cell — they do not trigger cross-cell navigation.

Vim modality in cell editors

Cell editors are Obsidian’s native editors with vim injected via registerEditorExtension(). Full Vim modality is supported: Normal, Insert, and Visual modes all work within a single table cell.

  • Tab / Shift+Tab navigate between cells, wrapping across rows (Tab at the last cell of a row moves to the first cell of the next row; Shift+Tab at the first cell wraps to the last cell of the previous row). When table-nav is enabled, Tab exits the cell editor and returns to table-nav on the destination cell.
  • When table-nav is enabled: Escape in normal mode returns to table-nav. h/j/k/l and w/b/e in normal mode move the cursor within the cell; only when the cursor reaches a cell boundary do they exit to table-nav and navigate to the adjacent cell. This lets you use standard vim cursor movement inside cells after pressing Escape from insert mode.
  • When table-nav is disabled: Escape in normal mode stays in the cell; h/j/k/l and w/b/e cross cell boundaries directly via motion overrides.
  • Register sharing: Vim registers are shared between cell editors and the main document.
  • Which-key: Which-key popups work in cell editors.

Cell editors use Live Preview

Cell editors use Obsidian’s Live Preview rendering. Markdown syntax like wikilink brackets ([[ ]]) and formatting marks are hidden during editing, but the underlying text is preserved.

Animated cursor in cells

When the animated cursor is enabled, table cell editors use the native vim cursor as the steady-state renderer. The canvas-based animated cursor cannot reliably render above table cell content due to CSS stacking contexts. Cross-cell navigation (h/j/k/l) snaps the cursor to the destination cell. Within a single cell, the native cursor renders normally.

Multi-line cell content

In insert mode, Shift+Enter inside a cell editor creates a line break, which Obsidian writes to the source as <br>, so the table structure stays valid. Enter moves to the cell below and, on the last row, adds a row. Measured in Obsidian 1.13.7.

Table row text objects

Wherever a table is plain text — Source mode, a revealed table in reveal mode, or raw — you can operate on entire table rows using the ir and ar text objects:

  • ir: Selects the inner row content (everything between the first and last | pipes, excluding the pipes themselves).
  • ar: Selects the around row content (the entire line including the leading and trailing pipes).

These text objects are useful for quickly deleting, changing, or yanking whole rows while editing the Markdown source.

Info

You can configure the table widget mode in Settings → Vim Motions → Table widget in live preview, or via set tablewidget=auto / set tablewidget=native / set tablewidget=reveal in your vimrc. set tablewidget=raw still works but is deprecated — see below.

Ex commands

The following Ex commands are available for table manipulation:

CommandShortDescription
:tablerowbefore:tablerowbAdd row above
:tablerowafter:tablerowaAdd row below
:tablerowup:tablerowuMove row up
:tablerowdown:tablerowdMove row down
:tablerowdelete:tablerowdeDelete row
:tablecolbefore:tablecolbAdd column left
:tablecolafter:tablecolaAdd column right
:tablecolleft:tablecollMove column left
:tablecolright:tablecolrMove column right
:tablecoldelete:tablecoldDelete column
:tablealignleft:tablealignlAlign column left
:tablealigncenter:tablealigncAlign column center
:tablealignright:tablealignrAlign column right
:tableinsert:tableiInsert a new table
:tablerealign:tablereaRealign the table

See known-limitations > Tables for detailed technical limitations.