tirenvi.nvim

Markdown & CSV table editor for Neovim — structural editing, pure text, always valid.

Supports Markdown and CSV out of the box.

Edit tables anywhere — including arbitrary text files via the Tir-embedded format.

Markdown (GFM)

Edit Markdown tables structurally.

Raw → aligned → edit → back to raw (lossless).

CSV / TSV

Raw → aligned → edit → back to raw (lossless).

Embedded tables (NEW)

Edit tables embedded inside source code, configuration files, or plain text documents without changing the surrounding text.

For example, tirenvi can edit tables embedded in Python source code:

# | Name  | City   |
# | ----- | ------ |
# | Alice | Tokyo  |
# | Bob   | Osaka  |

print("Hello Tir")

Use :Tir toggle to switch between the original text and the structured table view.

For details about the embedded table format, see the tir-embedded documentation.

Demo coming soon.

Design Philosophy

• Vim-first
• Text-only buffer
• Structurally safe
• Fully reversible transformation
• No hidden metadata
• Always valid

Why?

Markdown and CSV are text — but they represent structure.

Tirenvi lets you edit tabular data structurally, while staying in Vim’s native editing model.

You edit text. Tirenvi preserves structure.

Core Architecture

At the center is: TIR — Tabular Intermediate Representation

flat (gfm markdown, csv, tsv, ...)
        ↓ external parser
TIR (intermediate representation)
        ↓ tirenvi
tir-buf (structured buffer view)

Editing takes place tir-buf format.

On save:

tir-buf → TIR → original flat format

Key principles:

• The buffer contains only text
• No hidden shadow buffer
• No custom buffer type
• Transformations are reversible
• TIR is the source of truth
• Buffer structure can temporarily diverge during editing
• Structural repair is explicit and controllable

Edit tables directly in Vim while preserving a structured internal model.

Features

• Render CSV/TSV/GFM into an aligned structured view
• Edit tables embedded in any text file (Tir-embedded)
• Multiline cell support with preserved line breaks
• Column width control with wrapping support
• Three width modes: nowrap, wrap, and auto
• Preserve original file format on save
• Toggle raw ↔ structured view
• Immediate or deferred structural repair
• Dirty line tracking and highlighting
• Automatic wrap management for plain and grid views
• Grid-aware join that preserves column structure
• Column text objects for structural editing
• Structural motions for navigating between cells and blocks
• Works with native Vim motions and operators
• External parser architecture (extensible)
• Uses standard Vim editing

Structural Integrity Model

Tirenvi maintains a structured internal table model while allowing temporary buffer inconsistencies.

In deferred repair mode:

• Invalid table edits are allowed temporarily
• Dirty lines are tracked incrementally
• Internal attrs/model state remains structurally valid
• Buffer structure may temporarily diverge from the model
• :Tir redraw synchronizes the buffer with the internal model

In immediate repair mode:

• Invalid structural edits are repaired automatically
• Normal mode edits are repaired immediately
• Insert mode edits are repaired after leaving Insert

Tirenvi respects Vim’s undo tree.

Historical undo states are not rewritten, even if they contain temporary structural inconsistencies.

Installation

lazy.nvim

{
  "kibi2/tirenvi.nvim",
  dependencies = {
    { "kibi2/tir-csv", build = "pip install ." },
    { "kibi2/tir-gfm-lite", build = "pip install ." },
    { "kibi2/tir-embedded", build = "pip install ." },
    { "tpope/vim-repeat" }, -- Optional: enables '.' repeat for column width operations
  },
  config = function()
    require("tirenvi").setup {}
  end,
}

The required parser packages are installed automatically when using lazy.nvim.

vim-plug

Plug 'kibi2/tirenvi.nvim'

" Required parsers
Plug 'kibi2/tir-csv' { 'do': 'pip install .' }
Plug 'kibi2/tir-gfm-lite' { 'do': 'pip install .' }
Plug 'kibi2/tir-embedded' { 'do': 'pip install .' }

" Optional: enables '.' repeat for column width operations
Plug 'tpope/vim-repeat'

Requirements

• Neovim >= 0.10
• UTF-8 environment

Optional parsers

PukiWiki support is optional.

pip install tir-pukiwiki

Usage

Automatically activates based on filetype (via parser_map):

• csv
• tsv
• markdown
• pukiwiki

For embedded tables, use :Tir toggle to switch between the original text and the structured table view.

Custom parser mapping:

require("tirenvi").setup({
  parser_map = {
    csv = { executable = "tir-csv", required_version = "0.1.4" },
    tsv = { executable = "tir-csv", options = { "--delimiter", "\t" }, required_version = "0.1.4" },
    markdown = { executable = "tir-gfm-lite", allow_plain = true, required_version = "0.1.6" },
    ["*"] = { executable = "tir-embedded", allow_plain = true, embedded = true },
    pukiwiki = { executable = "tir-pukiwiki", allow_plain = true, required_version = "0.1.1" },
  }
})

Commands

Command	Description
:Tir width{=+-}[count]	Adjust column width by count (=: set, +/-: increment/decrement)
:Tir width?	Show the current table width settings.
:Tir fit{=+-}[count]	Adjust table span by count (=: set, +/-: increment/decrement)
:Tir wrap	Toggle nowrap ↔ wrap|auto width mode
:Tir redraw	Redraw and reformat dirty tables
:Tir toggle	Toggle raw ↔ structured table view
:Tir repair enable	Enable automatic structural repair
:Tir repair disable	Disable automatic structural repair
:Tir repair toggle	Toggle automatic structural repair
:Tir repair	Deprecated. Will be removed in v0.6.Use :Tir redraw instead

Operations that would break structure are automatically corrected.

Column width operations support . repeat when vim-repeat is installed.

Native Vim editing commands work as usual.

• dd, yy, p, D, o, R, J, and more
• Command-line command
• Visual mode command

No special editing mode.

Inspecting the current width settings

Use:

:Tir width?

Example output:

mode=nowrap span=23 col=1/3 header="Name" widths=[5*,3,11]

This displays the current width mode, table span, selected column, column widths, and other table information.

Width modes

Tirenvi supports three width modes:

• nowrap – Prevents wrapping inside cells. Best for editing cell contents.
• wrap – Keeps the table within a fixed width by wrapping cell contents.
• auto – Automatically switches between readable wide tables and compact wrapped tables depending on the available window width.

Editing Tips

• Inserting a line above the first row of a table creates a normal text line.
• Inserting a line below the last row appends a new table row.
• Press D at the beginning of a table row to split the table.
• Press D at the beginning of the second column to clear the cell contents.

Column Editing

Columns are structural units.

To modify a column:

1. Select a column using text objects (vil, val, v3al)
2. Apply standard operators (d, p, etc.)

require("tirenvi").setup({
  textobj = {
    column = "l",
    cell = "c",
  },
})

Cell Editing

Cells are structural units within a table.

To modify a cell:

1. Select a cell using text objects (vic, vac, v3ac)
2. Apply standard operators (d, y, p, etc.)

vic selects the cell content without the left border, while vac also includes the left border.

Wrapped cells are selected across multiple lines.

Motions

Structural Motions

Navigate through the logical structure of a TIR buffer.

vim.keymap.set({ 'n', 'o', 'x' }, '<C-h>', require('tirenvi').motion.cell_prev,
  { expr = true, desc = 'TirEnvi: previous cell' })
vim.keymap.set({ 'n', 'o', 'x' }, '<C-l>', require('tirenvi').motion.cell_next,
  { expr = true, desc = 'TirEnvi: next cell' })
vim.keymap.set({ 'n', 'o', 'x' }, '<C-k>', require('tirenvi').motion.block_top,
  { expr = true, desc = 'TirEnvi: block top' })
vim.keymap.set({ 'n', 'o', 'x' }, '<C-j>', require('tirenvi').motion.block_bottom,
  { expr = true, desc = 'TirEnvi: block bottom' })

• Ctrl-h / Ctrl-l: previous / next cell
• Ctrl-k / Ctrl-j: top / bottom of block

These motions support counts and Visual mode.

Pipe Motions

Navigate horizontally by table separators.

vim.keymap.set({ 'n', 'o', 'x' }, '<leader>tf', require('tirenvi').motion.f, { expr = true })
vim.keymap.set({ 'n', 'o', 'x' }, '<leader>tF', require('tirenvi').motion.F, { expr = true })
vim.keymap.set({ 'n', 'o', 'x' }, '<leader>tt', require('tirenvi').motion.t, { expr = true })
vim.keymap.set({ 'n', 'o', 'x' }, '<leader>tT', require('tirenvi').motion.T, { expr = true })

They behave like Vim's f/F/t/T, but target table separators.

; and , continue to repeat as usual.

Note: There are two types of pipes (continuation and non-continuation), so motions may behave differently across lines.

What Tirenvi Is Not

• Not a spreadsheet
• Not a new editing mode
• Not a hidden AST editor
• Not a file-format converter

It is a structured text editor layer.

Roadmap

Ideas

• VS Code support
• Copy and paste data with spreadsheets
• Simple calculations (sum, count, ave, max, min, sequence numbers)
• Sort rows and columns
• Integration with hydra.nvim
• Outline mode

Comparison

Feature	Tirenvi	csv.vim	Spreadsheet tools
Native Vim editing	✅	⚠️	❌
Always structurally valid	✅	❌	⚠️
No file format change	✅	❌	❌
No custom buffer type	✅	❌	❌
Toggle raw view	✅	❌	❌
Automatic wrapping	✅	❌	⚠️
Grid-aware join	✅	❌	❌
Markdown	✅	❌	❌
Embedded table	✅	❌	❌

Tirenvi prioritizes structural safety with Vim purity.

Contributing

The architecture centers around:

• flat ↔ TIR (external)
• TIR ↔ tir-buf (internal)

Large changes should respect this separation.

Please open an issue before major design proposals.

License

MIT License.