DEV Community

Cover image for Use your Obsidian vault from Neovim, organized by project
Abhishek Sharma
Abhishek Sharma

Posted on

Use your Obsidian vault from Neovim, organized by project

#neovim #obsidian #showdev #productivity

I built notes-nvim because I wanted to use my Obsidian vault from inside Neovim without leaving my project.

Obsidian is great for storing notes — graph view, mobile sync, plugin ecosystem. But my actual work happens in Neovim, and every Alt-Tab over to grab something from my vault was a small context-switch tax. Multiply that by a day of deep work and it adds up.

notes-nvim points at any markdown directory — your existing Obsidian vault, a plain ~/notes folder, anything — and exposes it inside Neovim, organized automatically by project. When you're inside my-api, your notes live under my-api/. When you switch to dotfiles, you're looking at dotfiles/. Plain markdown, no custom format, your vault stays portable.

The core idea

Most note plugins go one of two ways:

  1. Project-local — notes live inside the project folder. Clean in theory, but they end up in .gitignore purgatory and scatter across dozens of repos.
  2. Global flat pile — one big notes folder. Works until you have 200 files and no way to filter by context.

notes-nvim takes a third path: all notes live in one central directory (~/notes by default), but they're automatically organized by project root. When you're inside my-api, your notes go to ~/notes/my-api/. When you switch to dotfiles, you're looking at ~/notes/dotfiles/.

~/notes/                ← can be your existing Obsidian vault
  daily/                ← one shared daily log across all projects
    2026-04-26.md
    2026-04-25.md
  my-api/
    _index.md           ← auto-created, links to every note in the project
    auth.md
    api-design.md
  dotfiles/
    _index.md
    zsh.md
Enter fullscreen mode Exit fullscreen mode

You get the organization of project-local notes without the mess of scattering files across repos.

Using it with your existing Obsidian vault

If you already have an Obsidian vault, point notes-nvim straight at it:

{
  "abhsss96/notes-nvim",
  opts = {
    notes_dir = "~/Documents/ObsidianVault",
  },
}
Enter fullscreen mode Exit fullscreen mode

The plugin treats it like any markdown directory. Notes you create from Neovim show up in Obsidian on next open. Notes you create in Obsidian are searchable and openable from Neovim. Your vault stays a vault — Obsidian sync, mobile, and plugins keep working.

Native Obsidian features like [[wikilinks]] and embeds aren't fully resolved inside Neovim yet — that's the next big direction (more on this below).

Features at a glance

  • Daily notes — :NoteToday opens today's YYYY-MM-DD.md, shared globally across all projects
  • Project index — _index.md is auto-created per project and backlinks every note you create
  • Note from visual selection — select code in visual mode, hit <leader>ns, get a new note pre-populated with the snippet, source file, and line range
  • Link-safe rename — :NoteRename updates every markdown link pointing to the old file
  • Tag search — find notes by #hashtag or YAML tags: frontmatter
  • Recent notes — :NoteRecent surfaces notes you visited lately via oldfiles
  • Multi-picker — works with snacks.nvim, telescope, fzf-lua, or the built-in vim.ui.select
  • File browser — opens in oil.nvim, nvim-tree, neo-tree, or netrw — whichever you have
  • snacks.dashboard integration — show recent notes on your startup dashboard
  • which-key — <leader>n group registered automatically
  • Health check — :checkhealth notes-nvim tells you what's wired up and what's missing

Installation

lazy.nvim (recommended):

{
  "abhsss96/notes-nvim",
  opts = {
    notes_dir = "~/notes",
  },
}
Enter fullscreen mode Exit fullscreen mode

That's it for a working setup. The plugin auto-detects your fuzzy picker and file browser — no extra wiring required for most setups.

Commands and keymaps

All commands are available as both Ex commands and keymaps under <leader>n:

Command Keymap What it does
:Note [name] <leader>no Open or create a note in the current project
:NoteToday <leader>nt Open today's daily note
:NoteIndex <leader>ni Open _index.md for the current project
:NoteFind <leader>np Fuzzy-find notes in the current project
:NoteFindAll <leader>na Fuzzy-find notes across all projects
:NoteRecent <leader>nr Browse recently opened notes
:NoteBrowse <leader>nb Open project notes folder in your file browser
:NoteGrep <leader>ng Live-grep inside the current project's notes
:NoteGrepAll <leader>nG Live-grep across all notes
:NoteFindByTag — Pick a tag and jump to matching notes
:NoteFromSelection <leader>ns Create a note from a visual selection
:NoteRename [name] — Rename the current note and rewrite all links

The feature I use most: Note from selection

This is the workflow killer that made me build the plugin in the first place.

You're reading through code — maybe debugging, maybe doing a review — and you land on a function you need to reason about later. Select it in visual mode, press <leader>ns, give the note a name, and you get this:

# Authenticate function

Created: 2026-04-26

Source: `src/auth.lua` lines 42–58
Enter fullscreen mode Exit fullscreen mode 
local function authenticate(user)
  local token = db.find_token(user.id)
  if not token or token.expires_at < os.time() then
    return nil, "token expired"
  end
  return token
end
Enter fullscreen mode Exit fullscreen mode

Source file, line range, and filetype are all captured automatically. Your future self will know exactly where this came from.

Tag search

notes-nvim understands two tag formats so you don't have to pick one:

YAML frontmatter:

---
tags: [neovim, workflow, auth]
---
Enter fullscreen mode Exit fullscreen mode

Inline hashtags:

Ran into a weird edge case with token refresh. #auth #debugging
Enter fullscreen mode Exit fullscreen mode

:NoteFindByTag scans both formats and gives you a picker of all tags in the current project. :NoteFindByTagAll does the same globally.

Custom templates

New notes are created from a Lua template function, so you can inject whatever frontmatter or boilerplate you want:

require("notes-nvim").setup({
  template = function(ctx)
    return string.format([[
---
title: %s
project: %s
date: %s
tags: []
---

# %s

]], ctx.title, ctx.project, ctx.date, ctx.title)
  end,
})
Enter fullscreen mode Exit fullscreen mode

The ctx table has title, filepath, project, and date — enough to build most templates.

snacks.dashboard integration

If you use snacks.nvim, you can show recent notes right on your startup screen:

require("snacks").setup({
  dashboard = {
    sections = {
      { section = "header" },
      { section = "keys" },
      require("notes-nvim.dashboard").snacks_section({
        limit = 5,
        title = "Recent Notes",
      }),
      { section = "startup" },
    },
  },
})
Enter fullscreen mode Exit fullscreen mode

What I want to build next — and where I'd love input

This is where you come in. notes-nvim is at v1.0 and the core workflow is solid, but there's a lot of room to grow. The biggest direction I'm focused on next:

  • Deeper Obsidian compatibility — [[wikilink]] resolution and navigation, alias support from frontmatter, embed (![[file]]) handling, and other vault-native features. The goal is for notes-nvim to be a first-class Obsidian companion inside Neovim, not just a markdown reader.

A few other things on the list:

  • Templates per project — different boilerplate for different project types (e.g., a meeting note template for work projects, a learning note for side projects)
  • Note linking / backlinks — jump to all notes that link to the current one
  • Inline preview — float a preview of a linked note on hover
  • Export — push a note or a project's notes to a markdown directory ready for a static site
  • Git integration — auto-commit notes directory on save, or show a diff of today's notes
  • Note archiving — move old notes to an archive without breaking links

If you use both Obsidian and Neovim, I'd especially love to hear what's missing for you. Which Obsidian features do you reach for most that you'd want inside Neovim? And for Neovim users without an Obsidian vault — what does your current note setup look like, and what's the one thing that still makes you reach for an external app?

Drop a comment below — I read all of them and a good chunk of the features above came from conversations with other Neovim users.

Links

Built with Lua. Tested on Neovim 0.9+. MIT licensed.

Top comments (0)