vaultview.nvim

A Neovim plugin to visualize your notes vault in a board-style view — for quick, contextual overviews without relying on a file tree (that is limited for this sort of overview).

---

VaultView allows users to create customizable boards that give a quick, visual overview of their note vault. Instead of navigating through a file tree, VaultView parses and displays your notes in boards or matrices — giving you an at-a-glance view of what’s inside and what each note contains.

With it, you can:

• Quickly browse your vault in a structured, board-like interface.
• See summaries or key content (like headings, links, or metadata) from your notes.
• Open notes directly in Neovim or Obsidian.
• Navigate the boards fluidly using Vim motions or custom pickers.

Table of Contents

• Features

• Examples

• How it works

• Why this plugin

• External dependencies

• Installation

• Configuration

• Input and Content selectors

• Custom parsers

• Usage

• Keybinds inside VaultView UI

• Roadmap

• Known Issues

⭐ Features

• Search / Parse / Display specific files in a matrix or board view
• Open the corresponding file in Neovim or Obsidian
• Navigate between board entries using Vim motions or custom pickers
• Fully customizable boards — define what subset of your vault each one displays
• Access the files of your vault for quick edit from any Neovim project

🪄 Examples

Daily Notes Board (Carousel Layout):

MOC Board (Columns Layout):

Quick edit of a file from the board:

⚙️ How it works

A board in VaultView consists of two main parts:

1. Board Data

The data is generated by a parser, which:

• Takes all (or a subset) of your vault’s files => “Input Selection”
• Organizes it into a structured format => “Board Data Structuring”
• Extracts and aggregates relevant information for each entry => “Content Selection”

Board
├── Pages
│    ├── Lists (one column/block per list)
│    │    ├── Entries (one card per entry)
│    │    │    └── Content (displayed in cards)

Currently Supported Parsers:

• Daily Note Parser -> Retrieves all daily notes in your vault, sorts them by year/month, and extracts headings for each day.
• MOC Parser -> Finds all your MOC files and, for each one, lists all files linking to it — along with their headings (to display a TOC inside each card).

1. View Layout

The layout determines how the parsed data is displayed.

Currently Supported Layouts:

• Vertical Carousel
• Columns

💡 Why this plugin

I love Obsidian — especially for features like the Excalidraw plugin and great table handling. However, when it comes to navigation with hjkl and text editing, nothing beats Neovim.

What I missed most in Obsidian was a quick way to visualize my vault based on certain criteria — for example:

• Seeing what’s inside all my MOCs (Maps of Content)
• Browsing through all my Daily Notes

Obsidian has Dataview and Bases, but:

• They’re confined within Obsidian’s UI.
• They require a specific query/config language.
• They lack the power of Vim motions.

I actually started thinking about VaultView before Obsidian Bases even existed — and it turned out to be a great way to learn Lua and Neovim plugin development.

External dependencies

• ripgrep

Installation

• lazy.nvim

{
"fvalenza/vaultview",
dependencies = { "ColinKennedy/mega.cmdparse", "ColinKennedy/mega.logging", "folke/snacks.nvim" },
}

Configuration

• lazy.nvim

return {
"fvalenza/vaultview",
dependencies = { "ColinKennedy/mega.cmdparse", "ColinKennedy/mega.logging", "folke/snacks.nvim" },

keys = {
{ "<leader>vv", "<Plug>(Vaultview)", mode = "n", desc = "Open VaultView" },
},

config = function()

vim.g.vaultview_configuration = {
vault = {
path = "/path/to/your/vault", -- full path to your vault
name = "myVault",
},
user_commands = {
input_selectors = { -- custom input selectors can be defined here and chosen in the board configuration
list_files = { -- Hardcoded list of files
"/path/to/file1.md",
"/path/to/file2.md",
"/path/to/file3.md",
},
lua_function = function(path)
-- Custom Lua function that returns a list of files
end,
shell_command = [=[ your_shell_command ]=], -- Custom shell command to list files
},
entry_content_selectors = { -- custom content selectors can be defined here and chosen in the board configuration
},
},
boards = {
{
name = "dailyBoard", -- name of the board as printed in the top of UI
viewlayout = "carousel", -- how information is displayed in the view -> currently supported layouts: "carousel", "columns"
subfolder = "vault/0-dailynotes", -- optional subfolder inside vault to limit the scope of the input files
input_selector = "yyyy-mm-dd_md",-- Input Selection = get the files to be used as board inputs by the parser to build the board data
content_selector = "lvl2headings_noexcalidraw_awk", -- Content selection = get the content(lines) to display in the card associated to each entry (within lists)
parser = "daily", -- parser used to retrieve information to display in the view -> currently supported parsers: "daily", "moc"
-- show_empty_lists = false, -- TODO: not implemented yet
},
{
name = "mocBoard",
parser = "moc",
viewlayout = "columns",
subfolder = "vault/1-MOCs",
input_selector = "all_md",
content_selector = "lvl2headings_noexcalidraw_awk",
},
},
}
end,
}

Input and Content selectors

The plugin comes with some default input and content selectors that can be used in the board configuration. In the configuration one can specify custom ones for input selector as either : a list of files, a shell command returning a list of files, or a Lua function returning a list of files. content_selectors only accepts shell commands returning content lines for each entry. The current default ones are:

local input_selectors = {
all_files = [[find %q -type f | sort ]],
all_md = [[find %q -type f -name '*.md' | sort ]],
["yyyy-mm-dd_md"] = [[find %q -type f | sort | grep -E '/[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])\.md$']],
}

local content_selectors = {
all_headings = [=[grep -E '^#+[[:space:]]+.+' %q | sed -E 's/^#+[[:space:]]+//' ]=],
lvl2headings_noexcalidraw_awk = [=[awk '/^# Excalidraw Data/ { exit } /^##[[:space:]]+.+/ { sub(/^##[[:space:]]+/, ""); print }' %q]=],
lvl2headings_noexcalidraw_rg = [=[rg --until-pattern '^# Excalidraw Data' '^##[[:space:]]+.+$' %q | sed -E 's/^##[[:space:]]+//' ]=],
uncompleted_tasks = [=[grep -E '^\s*-\s*\[ \]' %q | sed -E 's/^\s*-\s*\[ \]\s*//' ]=], -- TODO test
completed_tasks = [=[grep -E '^\s*-\s*\[x\]' %q | sed -E 's/^\s*-\s*\[x\]\s*//' ]=], -- TODO test
tasks = [=[grep -E '^\s*-\s*\[[ x]\]' %q | sed -E 's/^\s*-\s*\[[ x]\]\s*//' ]=], -- TODO test
}

Custom parsers

One can provide in the configuration their own custom parsers by providing a function to the “parser” field of a board configuration. The function should take as input the vault subtable of the configuration and the board configuration table:

--- parse a vault folder to create a board data structure depending on the board configuration
---@param vault configuration of the vault {path: string, name: string}
---@param user_commands configuration of user commands {input_selectors: table, entry_content_selectors: table}
---@param boardConfig configuration of the board {name:string, parser: string|function, viewlayout: string, subfolder: string, pattern: string}
---@return The BoardDataStructure as expected by a ViewLayout
parser = function(vault_config, user_commands, board_config)
end

Warning: As this plugin is still in early development, the API for custom parsers may change in future releases + pattern matching is currently very basic (see TODOs).

Usage

Once setup and your neovim instance running, you can use the following commands to interact with VaultView.

:Vaultview open
:Vaultview close
:Vaultview refresh

or you can map your preferred keybinding to <Plug>(Vaultview) to open the main VaultView window.

Keybinds inside VaultView UI

See default keybinds for details. May change in the future.

It’s planned to allow user configuration of keybinds in future releases.

Roadmap

See roadmap

Known Issues

• When opening a file associated to an entry with , and when quitting it to return to main window of the vaultview (“q”), it comes back to the first board instead of the previsouly active one
• Action to “center cursor/focus” on viewlayoutcarousel to fix