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.
Link to original
Keybinding Description ]\|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
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]cand[cbindings.
Table text objects
Table text objects
Operate on table cells with standard Vim operators.
Link to original
Keybinding Description i\|Inside table cell (content between pipes) a\|Around table cell (content plus trailing pipe)
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 containsfoo \| bar.\\|(escaped backslash followed by pipe) is treated as a real boundary.
Table manipulation
Table manipulation
Manage table structure using the
<leader>tprefix.Link to original
Keybinding Description <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
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
nativemode, they work when the cursor is inside the table. Inrevealmode they work on the revealed table through text-based equivalents, since it has no widget for Obsidian’s commands to drive. Inrawmode, use Source mode or manual Markdown editing.
Table auto-formatting
Vim Motions includes built-in auto-formatting for tables:
- Manual realignment: Use
<Leader>tror:tablerealignto realign a table’s columns at any time. In table-nav mode,=does the same. - The same output as Obsidian:
:tablerealignwrites 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 betweennativeandreveal. 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
revealmode,tableautorealigncan do it for you. - Obsidian does realign automatically, in
nativemode: its table editor realigns the columns when it commits a cell edit. Inrevealmode, which never uses Obsidian’s cell editor, the same happens only if you settableautorealigntoinsertleave, or totypingto 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):revealwhile the Neovim backend is connected, andnativeotherwise. 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 viaregisterEditorExtension(). 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.
| Configuration | Experience |
|---|---|
native + tablenav (default without the Neovim backend) | Full table-nav overlay with cell highlighting and structural commands |
native + notablenav | Native table editor with vim cell editing and cross-cell navigation |
raw | Raw markdown tables |
reveal | Obsidian’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, chooseset 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
Vselection 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/kor 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>tbindings, 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
Tabwalks 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,
TabandShift-Tabmove to the next and previous cell, wrapping across rows and skipping the separator, andTabin the last cell adds an empty row - In insert mode, inside a cell,
Entermoves to the same column in the next row, adding a row from the last one, andShift-Enterinserts 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; withtableautorealign=typingthe columns follow your text as you type. Oneuundoes 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,[rand the text objectsi|,a| - The column alignment commands,
<Leader>tal,<Leader>tacand<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:tablerealignrealigns.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 settableautorealign. - 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
| Key | Action |
|---|---|
h / j / k / l | Navigate between cells |
Tab / Shift+Tab | Navigate to next / previous cell (wraps across rows) |
{count}j, {count}l, etc. | Navigate with count prefix (e.g., 3j) |
i / a / c / s / Enter | Start editing the active cell |
Escape | Exit table-nav and return to the main editor |
o | Add a row below |
O | Add a row above |
dd | Delete the current row |
dc | Delete the current column |
J | Move the current row down |
K | Move the current row up |
H | Move the current column to the left |
L | Move the current column to the right |
I | Add a column to the left |
A | Add 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:
| Key | In cell | At boundary |
|---|---|---|
l | Move right within cell | Move to next cell (same row) |
h | Move left within cell | Move to previous cell (same row) |
j | Move down within cell | Move to same column in next data row (skip separator) |
k | Move up within cell | Move to same column in previous data row (skip separator) |
w / W | Move to next word within cell | Move to next cell |
b / B | Move to previous word | Move to previous cell |
e / E | Move to end of word | Move to next cell |
ge / gE | Move to end of previous word | Move 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+Tabnavigate 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:
Escapein normal mode returns to table-nav.h/j/k/landw/b/ein 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:
Escapein normal mode stays in the cell;h/j/k/landw/b/ecross 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+Enterinside a cell editor creates a line break, which Obsidian writes to the source as<br>, so the table structure stays valid.Entermoves 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=revealin your vimrc.set tablewidget=rawstill works but is deprecated — see below.
Ex commands
The following Ex commands are available for table manipulation:
| Command | Short | Description |
|---|---|---|
:tablerowbefore | :tablerowb | Add row above |
:tablerowafter | :tablerowa | Add row below |
:tablerowup | :tablerowu | Move row up |
:tablerowdown | :tablerowd | Move row down |
:tablerowdelete | :tablerowde | Delete row |
:tablecolbefore | :tablecolb | Add column left |
:tablecolafter | :tablecola | Add column right |
:tablecolleft | :tablecoll | Move column left |
:tablecolright | :tablecolr | Move column right |
:tablecoldelete | :tablecold | Delete column |
:tablealignleft | :tablealignl | Align column left |
:tablealigncenter | :tablealignc | Align column center |
:tablealignright | :tablealignr | Align column right |
:tableinsert | :tablei | Insert a new table |
:tablerealign | :tablerea | Realign the table |
See known-limitations > Tables for detailed technical limitations.